Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Application debugging by using the Tracer tool

Updated on May 31, 2022

To provide a top-quality experience for your software users, test and debug your applications by using the Tracer tool. You can test and debug multiple resources, for example, activities, data transforms, decision rules, service rules, parse rules, and processes. You can also troubleshoot offline-enabled applications from a browser by testing scripts when the application is running.

For example, you can trace the events that are related to queue processing to ensure that your application correctly queues tasks to process in the background. As a result, you increase the efficiency of your application and save time because you avoid further debugging that untraced events might cause.

You can select which rulesets, rules and events to trace; set breakpoints and watch variables; trace reference properties; select which requestor session to trace, and add custom events to Tracer output.

You can also trace services and listeners anywhere in the cluster by using the RuleWatch trace.

When you set up your trace conditions and start tracing, you can view the Tracer output in the Tracer window or save the Tracer output to your local system, so that you can analyze your system offline or share the results with other developers.

Note: When using this tool for Customer Service chat interactions, be aware that multiple requestors can serve a single browser session.
Note: The Tracer tool is not available during a test coverage session.

Tracer for Cosmos React applications

Apart from the standard Pega Platform applications and your custom applications, Tracer also supports applications that you build by using the Cosmos React. Because Cosmos React applications are stateless and rely on DX APIs, the Tracer results window reflects the scheme in which your application interacts with a browser during a browser session. For greater clarity, the results window groups events by request ID, because multiple requests can be active simultaneously, as in the following example:

Tracer results for Cosmos React
A Tracer results window for a Cosmos React UI application

For relevant training materials, see the Debugging application errors module on Pega Academy.

  • Tracer best practices

    Use Tracer best practices to make tracing easier and more efficient.

  • Tracer disk usage FAQ

    For effective debugging, Tracer creates a file with the details of traced events so that you can make an informed decision about processes in your application. When you trace a high number of events, the file size can become extensive. To avoid issues with disk usage, Tracer sets a limit on the file size. As a result, tracing your application has no impact on running of your system.

  • Configuring trace conditions

    Before you run the Tracer tool, optionally configure trace conditions, based on the activity, data transform, rule, and so on, that you are testing and debugging. If you do not configure trace conditions, the default conditions are used.

  • Tracing and capturing events

    After you have configured the trace conditions, you can begin tracing and capturing events. As you perform the work that you want to trace, the Tracer displays the traced events according to the selected trace conditions. Each event is a row in the Tracer window.

  • Tracing services

    You can use the Tracer to monitor any active requestor session. However, a service usually runs in a new requestor session with a requestor ID that is not created until the service begins processing. At that point, the processing that the service performs in that requestor session occurs so quickly (in less than one second), that it can be hard to catch the event to trace it.

  • Viewing Tracer results in the Tracer window

    To maintain the quality of your application, you can use the Tracer window to interact with Tracer results. Each row in the window represents an event. The Tracer records selected events from the rule executions, database operations, and other event types that you select when you configure the Tracer.

  • Offline debugging by using Pega-TracerViewer

    The Pega-TracerViewer tool presents and summarizes Tracer output data, that is saved in an .xml file, in an interactive table or tree format. By using TracerViewer, you can analyze the Tracer data offline to understand what happens on your system, determine where performance bottlenecks occur, and diagnose additional issues.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us