# Pega Tracer - A Practical Configuration Guide for Pega Developers

**URL:** <https://forums.pega.com/t/pega-tracer-a-practical-configuration-guide-for-pega-developers/11783>\
**Category:** General\
**Tags:** senior-system-architect, lead-system-architect, pega-platform\
**Created:** [April 27, 2026, 12:30pm UTC](https://forums.pega.com/t/pega-tracer-a-practical-configuration-guide-for-pega-developers/11783 "2026-04-27T12:30:34Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![LeandroTaveira](https://yyz2.discourse-cdn.com/pega/user_avatar/forums.pega.com/leandrotaveira/32/21791_2.png) [@LeandroTaveira](https://forums.pega.com/u/LeandroTaveira)\
**Post date:** [April 27, 2026, 12:30pm UTC](https://forums.pega.com/t/pega-tracer-a-practical-configuration-guide-for-pega-developers/11783/1 "2026-04-27T12:30:34Z")

</div>

> **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](https://docs.pega.com/bundle/platform/page/platform/app-dev/application-debugging-using-tracer.html).

> 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:

1. **Events to Trace & Break Conditions** - what to capture and when to pause
2. **Event Types to Trace** - which rule categories to monitor
3. **RuleSets to Trace** - which application layers to watch
4. **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.

 ![](https://pega1.discourse-cdn.com/pega/original/3X/b/1/b11c8ec88ecc8e7a47ed7cbbcda9a7dbb80e166b.png)

## 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](https://docs.pega.com/bundle/platform/page/platform/app-dev/tracer-event-types-trace.html)**

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 |
| **Email** | 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

1. Enter the exact clipboard page name in the **Page name** field (`pyWorkPage`, `D_CustomerData`, `Param` etc)
2. Click **Add**
3. Run your scenario and look for the linked page snapshot inside the relevant Tracer event row

 ![](https://pega1.discourse-cdn.com/pega/original/3X/3/b/3bcec65633f13b298339ef84f200e8fbbfac1728.png)

### 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 `Param` alongside `pyWorkPage` to 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](https://docs.pega.com/bundle/platform/page/platform/app-dev/configuring-tracer-settings.html)**

→ **[Reducing Tracer event output — Pega Documentation](https://docs.pega.com/bundle/platform/page/platform/app-dev/reducing-tracer-event-output.html)**

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

> ⚠ **Critical constraint:** Enabling Abbreviate Events **automatically disables Pages to Trace AND Local Variables**. The platform enforces this, it is not optional.

> **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

> ⚠ **Critical constraint:** This setting can **significantly slow down system processing and response times**. Leave it OFF for everyday debugging.

### 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

> ⚠ **Critical constraint:** Cannot be used together with **Abbreviate Events** — they are mutually exclusive. Increases trace volume significantly for Activities with many variables.

### 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 `.xml` offline 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!

## References

- [The Tracer - overview](https://docs.pega.com/bundle/platform/page/platform/app-dev/tracer-event-types-trace.html)

- [Configuring Tracer settings](https://docs.pega.com/bundle/platform/page/platform/app-dev/configuring-tracer-settings.html)

- [Reducing Tracer event output](https://docs.pega.com/bundle/platform/page/platform/app-dev/reducing-tracer-event-output.html)

- [Configuring trace conditions](https://docs.pega.com/bundle/platform/page/platform/app-dev/configuring-tracer-conditions.html)

- [Tracer event types to trace](https://docs.pega.com/bundle/platform/page/platform/app-dev/tracer-event-types-trace.html)

---

<div class="post-metadata">

**Author:** ![KamilJaneczek](https://yyz2.discourse-cdn.com/pega/user_avatar/forums.pega.com/kamiljaneczek/32/19116_2.png) [@KamilJaneczek](https://forums.pega.com/u/KamilJaneczek)\
**Post date:** [April 27, 2026, 1:54pm UTC](https://forums.pega.com/t/pega-tracer-a-practical-configuration-guide-for-pega-developers/11783/2 "2026-04-27T13:54:19Z")

</div>

Thanks, for sharing, interesting reading, not only for beginners.

---

<div class="post-metadata">

**Author:** ![LeandroTaveira](https://yyz2.discourse-cdn.com/pega/user_avatar/forums.pega.com/leandrotaveira/32/21791_2.png) [@LeandroTaveira](https://forums.pega.com/u/LeandroTaveira)\
**Post date:** [April 27, 2026, 2:44pm UTC](https://forums.pega.com/t/pega-tracer-a-practical-configuration-guide-for-pega-developers/11783/3 "2026-04-27T14:44:09Z")

</div>

@KamilJaneczek , tks for the comment.