You are here: Reference > Tools, accelerators, and wizards > Tracer

Debugging with the Tracer tool

Use the Tracer to test and debug a variety of items, including activities, data transforms, decision rules, service rules, parse rules, and processes. You can:

See in summary or detail the processing that occurs as you or another requestor runs an activity
Pause and resume processing
View or set the value of watch variables
Drill down to step-by-step details
View trace events for any requestor connected to your server node, not just your own session.
Trace services/listeners anywhere in the cluster using RuleWatch trace.

Starting the Tracer

To start the Tracer tool:

Click Tracer in the developer toolbar in Designer Studio to trace your current session and Thread.
On the ruleforms for activities, data transforms, and services, select Actions > Trace.

Using the Tracer to test and debug

To use the Tracer:

Set up trace conditions.
Start tracing and capturing events. Click Play to trace and click Pause to stop tracing.
Optionally, save the Tracer output on your local system. By default, the system saves the output as an XML file.
Analyze the results.
To interactively examine details about an event, select values in the event's row in the Tracer display. See Understanding results. To analyze event details outside of the system, use the saved Tracer output file. See PDN article Using the Tracer tool to summarize Tracer XML output in Pega 7 to learn about and download a Windows viewer for Tracer output XML files.

Depending on your access role, some Tracer capabilities may not be available to you.

Step 1. Setting up trace conditions

Use the following controls at the top of the Tracer to set up trace conditions.

Control	Function	Help
Settings	Select which rulesets, rules, and events are to be traced.	Setting Tracer options
Breakpoints	Set or change breakpoints.	Setting breakpoints
Watch	Set or change watch variables.	Setting watch variables
Remote Tracer	Choose a requestor session other than your own. Wait a few seconds until the Tracer connects.	Selecting a connection

Step 2. Tracing and capturing events

After setting the trace conditions (such as the connection, events to trace, and breakpoints), the usual steps to trace and capture events are:

Click Play to start tracing events.
Move or minimize the Tracer window so that you can see the Designer Studio.
Perform the work that you want to trace (or in the case of tracing a requestor session other than your own session, wait for the system to perform the work in that session).
As the work is performed, the Tracer displays the traced events, according to the selected conditions. Each event is a row in the Tracer display.
When you have completed the events you want to trace, click Pause in the Trace window that you minimized in step 2 to stop tracing.

Note: If you are tracing data pages and see multiple "ADP Load" events with the same name, make sure you have only one Tracer window open. If you have multiple Tracer windows open, the event results may distribute across several windows, making it hard to evaluate the processes.

Tips for the Tracer display

If you only need to work offline with the Tracer results, and do not want to interactively view details of the displayed events, you can choose to suppress the event display by setting the Max Trace Events to Display to zero (0) at the bottom of the Tracer Settings window. Using this setting reduces the network traffic and workstation load if you only require the output in a file to work with it offline. When the events display is suppressed, save the file with the output results.

To reduce the quantity of detail sent to the Tracer, select the Abbreviate Events check box in the Tracer Settings window. This can improve performance of the requestor session being traced so that elapsed time statistics during tracing are closer to the normal value (when not being traced). However, when this box is selected, some watch variables may not operate correctly. Clear this box when watch variables are important to your debugging. See Setting Tracer options.

To change trace conditions after tracing has started, first pause tracing, and then use the appropriate option listed in the table in step 1.

Use the following controls to perform the corresponding action.

Control	Function
Pause	Pause the session being traced at the next possible moment. Displays by default.
Play	Resume processing after clicking Pause, or after a breakpoint event. Displays when tracing is paused.
Clear	Erase the displayed events.

Step 3. Optional: Save the Tracer output on your local system

Save the Tracer results to your local system for offline analysis.

By default, the system saves the output as an XML file. When tracing in a cluster, and more than one node reported events for a given RuleWatch, the system saves the output as a ZIP file that contains an XML file for each node that reported events. If only one node reported events, then the system saves the output as an XML file.

For information about a Windows viewer for Tracer output XML files, see PDN article Use the Tracer viewer tool to summarize Tracer XML output.

Step 4. Analyze the results

The Tracer display is interactive. The value in the Event Type column indicates that row's event. Click the row to view the details about that event.

For example, when the DB Query option is specified as a traced event, clicking on a row with SQL Queries in the Event Type column opens a window that displays details such as how long the query took, the SQL statement that was used, and other information.

When the results are saved as a local file, the file contains this detailed event information.

Troubleshooting Traces

If the node hosting your trace session fails and you encounter a duplicate trace error when you attempt to trace the same service again, you may need to clear stale trace sessions using the System Management Application (SMA).

Open topic with navigation