Disclaimer: This article is not a replacement for the official Pega documentation. For complete reference information on each Tracer setting, always consult the official Pega Tracer documentation.
The purpose of this guide is to provide scenario-based guidance that complements the official docs, focusing on what to select and when, not on redefining what each setting does.
Why I Wrote This
If you have ever opened the Pega Tracer and stared at the 40+ event type list wondering
“what on earth do I actually select for this scenario?” this guide is for you.
The official documentation covers each Tracer setting individually. What it lacks is exactly what this article provides: a scenario-driven, LSA-level guide that connects the settings to real debugging situations. After working through this in detail, I wanted to document the complete picture in one place, the event type breakdown by category with “When to Enable” guidance, the General Options trade-off analysis, and a cheat-sheet scenario table for the most common debugging situations you will face every day on Pega 25 Cloud.
This is the guide I wish had existed when I first opened the Tracer.
Introduction
The Pega Tracer is your primary real-time debugging tool inside Dev Studio. Think of it as a “flight recorder” for a single user session: it intercepts and logs rule executions, database calls, clipboard changes, and integration events as they happen, letting you pinpoint exactly where something goes wrong.
The Tracer has four configuration sections:
- Events to Trace & Break Conditions - what to capture and when to pause
- Event Types to Trace - which rule categories to monitor
- RuleSets to Trace - which application layers to watch
- Pages to Trace - which clipboard pages to snapshot
There is also a General Options panel with three additional toggles that significantly affect how the Tracer behaves.
Section 1: Events to Trace & Break Conditions
This is the most impactful section and the one most developers set-and-forget without fully understanding it.
Events to Trace
The checkboxes here control, for each rule type, whether Tracer records a row when execution starts, when it ends, or both. Think of them as “capture points.”
| Column | What It Records |
|---|---|
| Start | A row is written when the rule begins executing |
| End | A row is written when the rule finishes (including status and elapsed time) |
Recommendation: For most debugging, enable both Start and End for Activities and Activity Steps. For Data Transforms, enable Start and End for Data Transform Actions as well. This gives you the entry point and the result, so you can see exactly what happened inside each step and how long it took.
Why this matters: If you only capture End, you miss the input state. If you only capture Start, you never see the outcome. Both together give you the full picture.
Break Conditions
Break conditions pause the entire application processing at a specific moment so you can inspect the clipboard interactively.
| Break Condition | When It Pauses | Best Used For |
|---|---|---|
| Exception | Pauses on the first Java exception thrown | Catching unexpected runtime errors — the most broadly useful option |
| Fail Status | Pauses when pxMethodStatus = Fail |
Debugging explicit step failures in Activities |
| Warn Status | Pauses when pxMethodStatus = Warn |
Catching soft errors and warning conditions |
Recommendation for most cases: Enable Exception as a default. Add Fail Status whenever you are debugging an Activity that is failing silently. Skip Warn Status unless you are specifically hunting for warning-level logic.
Pega 25 Cloud note: Break conditions and breakpoints are not supported in Constellation (Cosmos React) UI applications. They work in Traditional UI (non-Constellation) applications only.
Section 2: Event Types to Trace
The official Pega documentation provides a complete list of all Tracer event types with functional descriptions here:
→ Tracer event types to trace — Pega Documentation
What the official docs do not provide is scenario-based guidance on when to enable each type. That is the purpose of this section.
The key principle: enable only what you need for the scenario you are debugging. Enabling everything at once floods the log and degrades session performance.
Below are the event types organized into logical groups, each with a When to Enable column that does not exist in the official documentation.
Process & Flow Logic
| Event Type | When to Enable |
|---|---|
| Flow | When a case is not routing correctly, skipping a step, or getting stuck |
| CaseType | When a case is not advancing through its life cycle as expected |
| Automation | When an automation step in a case silently fails or produces wrong output |
| Asynchronous Activity | When background processing (triggered post-save or via a queue) is not completing as expected |
| Interaction | When performance-profiling or correlating user actions to trace events |
Declarative & Decision Logic
| Event Type | When to Enable |
|---|---|
| Declare Expression | When a calculated property has an unexpected or stale value |
| Declare OnChange | When you suspect an unintended side effect is firing, or a side effect is not firing when it should |
| Declare Trigger | When background processing is triggered unexpectedly on save, or is not triggering at all |
| Declare Index | When report data is stale or a Declare Index is not updating after a case save |
| Declare Collection | When a collection-driven report or aggregate value is wrong |
| Declare Constraint | When validation is blocking unexpectedly or failing to block when it should |
| Declare DecisionMap | When a mapped property lookup returns the wrong value |
| Declare DecisionTable | When a table-based decision returns the wrong result |
| Declare DecisionTree | When a tree-based classification or routing decision gives the wrong outcome |
| Decision Data | When a decision strategy is receiving wrong or missing input data |
| AutoPopulate Properties | When a property that should be auto-populated is blank or has the wrong value |
Decisioning & AI (CDH / Pega AI)
| Event Type | When to Enable |
|---|---|
| Strategy | When a strategy produces wrong, empty, or unexpected proposition sets |
| Proposition Filter | When eligible propositions are being incorrectly excluded or included |
| Adaptive Model | When an adaptive model is not updating, scoring incorrectly, or behaving unexpectedly |
| Predictive Model | When a predictive score is wrong, null, or not being invoked |
| Scorecard | When a scorecard total is incorrect or a weight is not being applied |
| GenAI | When a GenAI step, agent, or coach rule is not triggering, producing wrong output, or failing silently |
Data & Database
| Event Type | When to Enable |
|---|---|
| Data Pages | When a Data Page is not loading, is returning stale data, or is triggering an unexpected reload |
| DB Query | When you suspect a slow query, a wrong filter condition, or an object is reading incorrect data |
| DB Cache | When performance is degraded and you want to verify whether repeated reads are being served from cache |
| DataSync | When offline sync or cross-application data synchronization is not completing or is producing conflicts |
| ADP Load | When an asynchronously-loaded Data Page is not completing its load, is loading with incorrect data, or is blocking other operations |
| Linked Page Hit | When investigating whether linked properties are resolving from cache (performance analysis) |
| Linked Page Miss | When linked properties are causing unexpected database reads or performance degradation |
| Locking | When you hit concurrency errors, deadlocks, or a case is locked when it should not be |
| Query Resolution | When a report is running unexpectedly slow or hitting the database instead of the search index |
Integration & Services
| Event Type | When to Enable |
|---|---|
| Services | When debugging an inbound API call into Pega, shows you what arrived and how it was processed |
| Connectors | When debugging Data Pages backed by REST connectors or integration failures |
| SOAP Messages | When an outbound SOAP integration is failing, returning unexpected responses, or sending malformed requests |
| When case-triggered email notifications silently fail | |
| Router | When debugging workbasket routing or assignment routing rules in multi-operator scenarios |
| Queue Processing | When a scheduled job or listener is not firing, is failing silently, or is behaving inconsistently across nodes |
| Push Notifications | When real-time UI push notifications (Constellation or Pega Pulse) are not being delivered or are going to wrong subscribers |
Stream, UI & Testing
| Event Type | When to Enable |
|---|---|
| Stream Rules | When a generated document, email template, or XML output has wrong content or fails to render |
| View Rules | When a Constellation UI screen is not rendering correctly, a field is missing, or a view condition is wrong |
| Parse Rules | When inbound data (from a service or file) is not being parsed into the clipboard correctly |
| Log Messages | When you want to see custom debug messages intentionally written into Activities or Data Transforms |
| Alert | When you want to correlate performance alerts with the trace events that caused them |
| Unit Test Case | When a unit test is failing and you need to see what happened inside the tested rule, not just the pass/fail result |
Section 3: RuleSets to Trace
Narrow your trace to the rulesets relevant to the feature you are debugging, rather than all rulesets, to dramatically reduce log noise and improve Tracer performance.
Section 4: Pages to Trace
This section lets you monitor specific clipboard pages in real time as Tracer runs. When a page you have registered is touched during a traced event, a “Properties on Page” link appears in that Tracer row, clicking it shows you the full state of that page at that exact moment in time.
How to Configure It
- Enter the exact clipboard page name in the Page name field (
pyWorkPage,D_CustomerData,Parametc) - Click Add
- Run your scenario and look for the linked page snapshot inside the relevant Tracer event row
Best Practices
- Add only the pages you are actively investigating, each additional page increases overhead
- Use it when you need to see property values on a page at a specific point in execution (before and after a Data Transform runs)
- This option is automatically disabled if you have Abbreviate Events turned on in the General Options panel
Pro tip: Combine Pages to Trace with a narrow event type selection to keep the log manageable. When tracing a looping Activity, add
ParamalongsidepyWorkPageto watch iteration counters change step by step.
General Options: Abbreviate Events, Expand Java Pages & Local Variables
The official Pega documentation describes what each of these three toggles does here:
→ Configuring Tracer settings — Pega Documentation
→ Reducing Tracer event output — Pega Documentation
What the docs do not tell you is when to use each one in practice. That is what this section adds.
Abbreviate Events
Turn it ON when:
- Your issue is timing-sensitive (e.g., race conditions, async processing) and you need elapsed-time statistics as close to reality as possible
- You only care about which rules ran, not the property values inside them
- You are doing a broad, high-volume trace and performance degradation is a concern
Bottom line: Turn it ON when performance and timing matter. Turn it OFF when you need deep property inspection.
Expand Java Pages
Turn it ON when:
- You are debugging an issue specifically related to a property with Java Pages mode
- Pega Support or a GSI asks you to capture this level of detail for a platform-level investigation
Local Variables
Turn it ON when:
- Debugging a complex Activity and you need to verify that variables are being assigned the right values at each step
- A step is producing unexpected output and you want to see the input variable state before it ran
- You are tracing looping logic and need to watch a counter or accumulator variable change through each iteration
The Three General Options at a Glance
| Setting | Turn ON When… | Turn OFF When… | Key Constraint |
|---|---|---|---|
| Abbreviate Events | Timing matters; you only need rule names and status | You need clipboard snapshots or variable values | Disables Pages to Trace AND Local Variables |
| Expand Java Pages | Debugging a Java Pages property specifically | Any standard debugging scenario | High performance overhead |
| Local Variables | Tracing Activity variable values step by step | Performance is a concern or log volume is too high | Incompatible with Abbreviate Events |
Practical Starting Configuration (Pega 25 Cloud, LSA-Level Debugging)
For the vast majority of debugging sessions, start here:
- Abbreviate Events → OFF — you almost always need the clipboard detail
- Expand Java Pages → OFF — unless you are specifically chasing a Java Pages property issue
- Local Variables → ON — genuinely useful for Activity debugging; the extra rows are worth it when hunting a variable assignment bug
If the Tracer itself is slowing the system so much that it affects the issue you are trying to reproduce, flip Abbreviate Events ON temporarily — just remember that Pages to Trace and Local Variables go dark when you do.
Scenario-Based Quick Reference
Use this table as your daily cheat sheet. Match your debugging scenario to the event types, break conditions, and pages that matter most.
| Debugging Scenario | Event Types to Enable | Break Conditions | Pages to Trace |
|---|---|---|---|
| Activity failing silently or producing wrong output | Flow, CaseType, Automation, Asynchronous Activity, Log Messages, Alert | Fail Status + Exception | pyWorkPage, Param |
| Case not routing / stuck in stage | Flow, CaseType, Declare DecisionTable, Declare DecisionTree, Declare Constraint | Exception | pyWorkPage |
| Declarative property has wrong or stale value | Declare Expression, Declare OnChange, Declare DecisionMap, AutoPopulate Properties | Exception | Page containing the property |
| Declare Trigger not firing or firing unexpectedly | Declare Trigger, Declare Index, Log Messages | Exception | pyWorkPage |
| Data Page not loading or returning stale data | Data Pages, ADP Load, DB Query, DB Cache | Exception | The specific D_ page |
| Database performance issue or wrong SQL | DB Query, DB Cache, Linked Page Hit, Linked Page Miss, Query Resolution, Locking | None | None |
| SOAP integration failing | SOAP Messages, Services, Data Pages, Log Messages | Exception | Integration clipboard page |
| REST connector / inbound service failing | Services, Connectors, Data Pages, Log Messages, Alert | Exception | D_ page for that Data Page |
| Queue Processor or Job Scheduler not running | Queue Processing, Asynchronous Activity, Log Messages, Alert | Exception | None |
| Push notification not delivered | Push Notifications, Stream Rules, Log Messages | Exception | None |
| CDH Strategy returning wrong propositions | Strategy, Proposition Filter, Decision Data, Adaptive Model, Predictive Model, Scorecard | Exception | CDH clipboard page |
| Decision Table / Tree giving wrong result | Declare DecisionTable, Declare DecisionTree, Declare DecisionMap, Decision Data | Exception | pyWorkPage |
| Scorecard or Adaptive Model scoring incorrectly | Scorecard, Adaptive Model, Predictive Model, Decision Data | Exception | Relevant scoring page |
| GenAI step not triggering or producing wrong output | GenAI, Flow, Automation, Log Messages | Exception | Relevant clipboard page |
| UI / Constellation screen not rendering correctly | View Rules, Stream Rules, Data Pages | Exception | pyWorkPage |
| Inbound message not parsing correctly | Parse Rules, Services, Log Messages | Exception | Clipboard page for parsed data |
| Unit test failing (PegaUnit) | Unit Test Case, Declare Expression, Declare DecisionTable, Log Messages | Exception | pyWorkPage, Param |
| Concurrent access / locking issue | Locking, DB Query, Asynchronous Activity | Exception | pyWorkPage |
| Data synchronization (offline / Process Fabric) | DataSync, Data Pages, Log Messages, Queue Processing | Exception | Relevant sync page |
| Email notification silently failing | Email, Flow, CaseType, Log Messages | Exception | pyWorkPage |
| Work Queue routing incorrect | Router, Flow, CaseType, Log Messages | Exception | pyWorkPage |
| Custom debug messages from developer | Log Messages, Alert | None | None |
Best Practices Summary
- Start narrow: Enable only the event types you need. A smaller trace is faster to record and faster to read.
- Use Abbreviate Events when you only care about rule names and status, not the full clipboard snapshot. This runs much faster.
- Send output to a file for high-volume traces: set Max Trace Events to 0, enable file output, and analyze the
.xmloffline with Pega-TracerViewer. - Remote Tracer lets you trace another user’s session, useful when debugging an issue that only happens for a specific test user.
- Watch conditions are your friend for declarative debugging: instead of setting a break on every step, watch for when a specific property value changes on a monitored page.
- Pair Pages to Trace with a narrow event list, the combination of a focused event type selection and a specific clipboard page snapshot gives you the cleanest, most readable Tracer output.
Conclusion
The Tracer makes much more sense once you realize it is three tools in one: an event recorder (Events to Trace), a category filter (Event Types to Trace), and an interactive debugger (Break Conditions + Pages to Trace). The General Options panel adds a fourth dimension, controlling the fidelity vs. performance trade-off.
The Scenario-Based Quick Reference above should give you a solid, bookmarkable starting point for every situation you will encounter on Pega.
If this article helped you, feel free to share it with your team and leave a comment below with scenarios you would like to see added to the cheat sheet. Happy debugging!