Configuring the Traces for Agents in AWI

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.

As a system administrator, you have two options to configure the Agent traces, through the INI files and through AWI. For more information about the traces configuration in the INI files, see Automation Engine. This topic explains how to configure them through AWI.

When configuring an Agent you can specify the following Trace settings:

  • Define how to distribute workload among Agents.

  • Restrict the number of report blocks to be stored in the Automation Engine database.

  • Specify the time interval for the periodic Automation Engine check.

For an overview about logs and traces, see Diagnostic Tools: Logs and Traces and Logging and Traces: Watch the Video.

Starting and Stopping Agent Tracing

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. You configure the trace options on the Advanced Options dialog. For information about what is traced and how trace data is collected, see below.

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:

  • On the Advanced Options dialog, in the Additional Trace Options section, you define a text string in Trace Search Key. This string signals the end of the trace. For example, this string can be 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. To do so, on the Advanced Options dialog, in the Trace Flags section, you set all the options (TCP/IP, File Transfer, Event and so on) to 0 (zero), and then click Apply.

Configuring the Trace Flags for Agents - What Is Traced?

Agent trace flags, trace flags in Agents, agent advanced options

In the Trace Flags section of the Advanced Options dialog you set the trace level for a number of Agent activities (TCP/IP, File Transfers, Events and so on). This determines the level of detail that the trace files will contain.

The options on this dialog depend on the type of Agent that you are defining. Generally, the trace values are 0–9 to indicate the level of detail collected, but values can be different for some Agents. Tracing is disabled when the trace value is 0 (zero) and the maximum level of detail is 9.

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.

Configuring Additional Trace Options for Agents - How Is Trace Data 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 in the Additional Trace Options section, 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! 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*.

Using Script Functions to Retrieve Logging and Tracing Information

The Automation Engine scripting language provides the following script functions that you can use in your scripts to output values to log or trace files_

See also: