Configuring the Traces for AE Processes in AWI

All Automation Engine processes 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 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 processes, CA Automic Support might ask you to temporarily enable tracing.

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 Automation Engine process 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.

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

Starting and Stopping Automation Engine Process Tracing

To Start Process Tracing

To start tracing, you need to set trace options that specify exactly what data is collected.

Go to the Administration perspective if you are not already there.
Expand Automation Engine Management and select Processes and Utilization.
Right-click a process and select Advanced Options. You configure the trace options in the Trace Flags section on the Advanced Options dialog. For information about what is traced and how trace data is collected, see below.

Important!

When you specify the trace options for a Work Process, these options apply to ALL your Work Processes (WPs, JWPs, DWPs, the PWP). This does NOT apply to CPs and REST processes; setting traces for a CP does not affect JCPs or REST processes.
Depending on the type of process, the meaning of the JCL trace flag is different. If you set it for REST processes, REST processes are traced; if you set it for any other process type, JCL is traced.

To Stop Process Tracing

On the Advanced Options dialog, in the Trace Flags section, set all the options (TCP/IP, Database, File Transfer, Srcall and so on) to 0 (zero), and then click Apply.

Configuring the Trace Flags for Processes - What Is Traced?

In the Trace Flags section of the Advanced Options dialog, you set the trace level for a number of process activities (TCP/IP, Database, Transfers, Srcall and so on). This determines the level of detail that the trace files will contain. 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) and the maximum level of detail is 9. A short description of each values is shown to the right of the number in each dropdown list.

To be able to set the Automation Engine trace level, your User definition must have the Create diagnostic information privilege.

Configuring Additional Trace Options for Work Processes - How Is Trace Data Collected?

For Work Processes (WPs, JWPs, DWPs, PWP) only!

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

You can use this option 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 Size

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.

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_