The Tracer
The Tracer is a tool available in the Pega Platform that helps you with troubleshooting. When an error occurs in an application, you must identify the source. By viewing the events that led to the error, you can find the root cause and fix the issue.
For example, a declare expression that is used to set a property value may return an unexpected value. This property value is used to determine whether a particular workflow stage should be skipped. The user notices that the case advances to an unexpected stage and finds that the declare expression property is not displayed in the UI. The Tracer tool documents the sequence of execution events allowing the user to troubleshoot this error.
View events with the Tracer
To view events when a case is processed, you use the Tracer tool to capture and view each event. For example, your application uses a data page to populate a drop-down list of cities. If the contents of the drop-down list are incorrect, such as the list includes a state instead of a city, you need to determine whether the control or the connection to the data source has an improper configuration.
The Tracer tool versus the Clipboard tool
As your application executes, Pega Platform™ logs all the processing events that result from application execution. Unlike the Clipboard tool, which presents the current value of properties in memory, the Tracer provides a complete log of the events that occur during case processing. This log allows you to identify the source of execution errors, such as Java exceptions or incorrect property values.
In the center of the following image, slide the vertical line to compare the Clipboard tool and Tracer tool.
Caution: Running the Tracer impacts application performance significantly due to the volume of data collected for rule execution. As a best practice, do not use the Tracer as a performance analysis tool. To learn more about using the Tracer, see Tracer best practices.
Identify errors in case processing
The Status column in the Tracer log helps you identify the processing steps that lead to an error. In the Tracer log, most steps return a status of Good, indicating that the step was completed successfully. If a step returns a status of Fail, the step is completed unsuccessfully. The following image shows the Tracer tool displaying a failed step.
An error in an application may only indicate the last step in a sequence of failed steps but not the cause of the fail sequence. Reviewing the sequence of events in the Tracer helps identify the root cause that leads to the error seen by users. In the Tracer tool, when you click on the failed step, the properties for that event are displayed.
Note: To learn more about identifying the root cause of errors, see Tracing and capturing events.
Check your knowledge with the following interaction.
Investigate application errors with the Tracer tool
By configuring the Tracer to monitor application execution, you can investigate issues and events logged by the Tracer to identify their cause.
Tracer displays each event on a separate row. The records are displayed according to the following color code:
- Gray – Activity processing
- Orange – Events from flow, decision, or declarative rules
- Light blue – PegaRULES database and cache operations
Note: For more information on the records the Tracer displays, see Tracer results window.
Tracer icon
You access the Tracer by toggling the Runtime toolbar in App Studio. Hover your pointer over the lower-right corner of the screen to see the Toggle runtime toolbar option. Or, you can access the Tracer tool from the Developer toolbar in Dev Studio.
Tracer events
Each event is logged in order of occurrence and is identified by a thread, event type, and status. The Name and Ruleset columns identify the rule name and the related ruleset for each line item.
In the following image, click the + icons to view details about the Name and Ruleset columns.
Event details
Click on a row within the Tracer tool to view details about the event in a new window. From this window, you can see the contents in memory at the time the event occurred, such as the page class and page name. When you finish reviewing the event properties, close the window to return to the Tracer tool.
Page properties and values
Selecting a line item in the Step Page column displays a list of page properties and their values at the time an event executes. You can use this information to determine whether the values are different than expected. For example, the line item for event 11391 shows an undefined step method in the Step Method column.
Properties example
The user clicks the pyWorkPage in the Step Page column for event 11391 to display the properties that are stored on the workpage at the time the event is executed.
Check your knowledge with the following interaction.
This Topic is available in the following Module:
If you are having problems with your training, please review the Pega Academy Support FAQs.
Want to help us improve this content?