Advanced Options - Tracing

The advanced Agent options allow you to specify the Trace settings, to distribute workload among Agents, to restrict the number of report blocks to be stored in the Automation Engine database and to specify the time interval for the periodic Automation Engine check.

The options that are available in the Trace Flags section depend on the type of Agent. For example, Windows Agents have an additional section (Additional Trace Options that other Agents do not have.

Setting the Trace Options

All agents can write trace files. Like log files, trace files keep a record of activities on a component. However, whereas log files record key events and messages, trace files record the entire program and data flow. This detailed information can be helpful for diagnosing difficult error situations or critical performance bottlenecks.

Although tracing can be useful, it generates huge amounts of data in a short time and this can decrease system performance significantly. For this reason tracing is usually disabled. However, when you have a complex error situation that might be related to one of your agents, CA Automic Support might ask you to temporarily enable tracing on the agent.

Important! Because tracing can have a noticeable negative effect on system performance, please set trace options only when the Support team instructs you to do so explicitly. Your support case assistant knows which values to set to collect targeted data with the lowest impact on your system performance.

Trace Flags Section - What Is Traced

In the Trace Flags section you set the trace level for a number of Agent activities (TCP/IP, File Transfers, Events and so on); which options are available depend on the type of Agent. Generally, the trace values are 0–9 to indicate the level of detail collected, but values can be different for some processes. Tracing is disabled when the trace value is 0 (zero).

Rapid Automation (RA) agents have an additional "RA" trace option. When tracing RA agents, you usually specify the highest trace level (99) but, as with all trace options, ask the Support team what they recommend. Please note that although some RA agents, such as RA Web Service REST Agent and RA Web Service SOAP Agent, allow you to set additional third-party library tracing in their UCXJCITX.INI file, you cannot enable third-party tracing remotely. For more information, see Agent RA Core.

Additional Trace Options - How Trace Data Is Collected

Error situations that occur sporadically or are not reproducible are difficult to trace. If you trace everything in the hopes of catching the error, trace files can quickly become hard to read or too big for the available disk space. Using a combination of the following trace options, you can better target your tracing while managing your disk capacity.

• Memory Trace

  If an agent allows tracing in memory, you can enable this option. You use it in combination with the Trace Search Key. The trace messages will be saved to a memory buffer until the search string is found, at which time tracing stops and the messages are written to one trace file on the disk. Without this option, trace files are written directly to the disk, as one or more files, depending on the Max. Trace Size setting.

• Memory Buffer Site

  The maximum trace size influences the size of the trace files that are written to the disk of the agent's host. How it works depends on whether the Trace Memory option is enabled:

  • Trace Memory enabled

    In this case, the trace component reserves the specified space on the disk in preparation for when the trace files is written. If the trace file size in the memory buffer exceeds the reserved space defined here, the trace component will continuously truncate the oldest messages in the trace file to make room for the newest.

  • Trace Memory disabled or unavailable

    When a trace file reaches the defined limit, the tracing component finishes writing the message or command that it was writing at that time. When the size of the current trace file exceeds this limit, the file is closed and a new trace file is opened.

  In all cases, the real size of the trace file tends to be larger than the maximum size defined because the trace component finishes writing the message or code that it is logging when the size limit is reached. Some script statements can be extremely long, so the file size will be noticeable larger than the limit set.

  Important to understand is that the purpose of the Max. Trace Size is to limit the space used in memory. The file representation that is then saved on the disk can be much bigger. For example, if you are using memory tracing, the file will be much bigger, because the trace data is written to the memory buffer in binary form but when the buffer is flushed onto the disk, the trace file is written in hexadecimal form, which explodes the file size.

  If you set the Max. Trace Size to 0 (zero) without memory tracing, this means that the trace file size is unlimited. However, with memory tracing set, the trace size cannot be lower than the default of 32MB. So, if you enter a value less than that, the system automatically treats it as if it were 32MB.

  Note: Regardless of the trace settings, if the agent crashes then tracing also stops. The last record will not be written. When the agent starts again, all trace options will be reset to the defaults that are defined in the agent's INI file.

• Trace Search Key

  You can enter a text string, such as a specific error message, that signals the end of tracing. When the tracing component encounters this string, it finishes writing the current message and then it stops tracing and resets all trace options to "0" (zero). You use this to help you focus on the area where the problem occurred and to manage disk space by preventing excessive tracing.

  Note: Wildcards are not automatically added. You must manually add them at the desired positions. For example: To write the trace when the specific agent WIN01 is mentioned, the correct string to search for is *WIN01*.

To Start Agent Tracing

To start tracing, you need to set trace options that specify exactly what data is collected. You can only set tracing options for agents that are enabled (running).

1. Go to the Administration perspective if you are not already there.
2. Expand the Agents & Groups menu and select Agents.
3. Right-click the agent and select Advanced Options.

To Stop Agent Tracing

Generally, when you set trace options for an agent, you specify a Trace Search Key, a string that signals the end of tracing, so that tracing stops automatically.

Tracing stops in one of the following ways:

• You define a text string in the search options (Trace Search Key) that signals the end of the trace, such as a specific error message.
• The agent runs into a critical error and stopped. In this case, when the agent starts again, tracing options are reset to the defaults that are defined in the agent's INI file.
• You disable tracing by manually changing the trace options to stop tracing:
  1. Open the Agents list.
  2. Right-click the agent to select Advanced Options.
  3. Set all options in the top part of the dialog to 0 (zero), and then click the Apply button.

See also:

• Controlled Computer Restart - Best Practices
• Agents (HOST)
• Agent Job Messenger