Tracer
Setting options

To cause Tracer output to include certain events, check one or more Events to Trace boxes. These options are most relevant to debugging activities (rather than flows or declarative rules).

Select the boxes that identify the events of interest.

To cause the Tracer to stop for specific events, check the Break Conditions check boxes. You can use the Tracer tool's Break button () to create other break conditions.

Use the Continue button () to continue, step-by-step, through an activity execution after any of the conditions in the following table causes processing to pause:

Select Expand Java Pages if the processing involves properties of mode Java Pages. This option can significantly slow processing.

Select Abbreviate events to limit the clipboard details sent to the Tracer tool.

Complete the middle portion of this form to trace the progress of flows, declarative rules, or decision trees rules.

For declarative rules, rows of the Tracer output show the operation of the dependency network — the forward and backward chaining computations that occur automatically.

Label	Description
Event	Optional. Leave blank in most cases. Enter an additional event type as instructed by Pegasystems Global support. Then click  Add   to enable tracing for this type.
Log Messages	Record each execution of the Log-Message method that has the Send Message to Tracer parameter selected.
Flow	Trace a flow execution. Rows of the Tracer output identify each flow start and end, each task (shape) start and end, and the connectors (arrows on the Visio diagram).
Constraints	Trace Constraints rules.
Declare Expression	Trace Declare Expression rules.
Declare Index	Trace Declare Index rules.
Declare OnChange	Trace Declare OnChange rules.
Declare Trigger	Trace Declare Trigger rules
Decision Tree	Trace decision tree rules (start only)
Decision Table	Trace decision table rules (start only)
Decision Map	Trace map value rules (start only).
Collection	Trace collection rules.
Locking	Trace locking operations. Tracer output shows each lock acquired and each lock released.
Services	Trace service rules and service activities. See Tracer — Tracing services.
Stream Rules	Trace stream rule execution.
Parse Rules	Trace Parse XML, Parse Structure, and Parse Delimited rules. Other parse rule types are not traced.
Auto Populated Properties	Trace the execution of auto-populated properties.

Tracing other events

As an advanced debugging technique, you can add custom events to Tracer output as follows:

1. Modify the activity rule (or other executable rule) you want to debug. Add a call to the standard function sendDebugMessagetoTracer(strMessage, strRuleSet) at appropriate places. This function is in the PegaRULES Utilities library. Because this function returns void, it can't be used in most methods. To include the function in a Java step, enter the call in the form:

   pega_rules_utilities.sendDebugMessagetoTracer(message, RuleSet)

2. Start the Tracer tool and then click the Options button.
3. In the Options panel, enter Debug in the Event Type field. Click  Add  .
4. Select the Debug check box that appears.
5. Select the RuleSet referenced by the function call.
6. Click  OK   to close the Options panel. Begin the activity you want to debug.

By default, the Tracer does not report changes to reference properties. To enable tracing of such changes:

1. Enter Reference Properties in the Event Type field. Click  Add  .
2. Select the Reference Properties check box that appears.
3. Click  OK   to close the Options panel.
4. Begin the operation you want to debug.

This panel lists all RuleSets you can access, in the order they appear in your RuleSet list.

To trace the execution of rules in a specific RuleSet, check the corresponding box. The list shows all the RuleSets in your RuleSet list, based on your access group and other sources.

The Tracer always enforces RuleSet access controls. Whether tracing your own session or another user's session, Tracer output never includes information about rules executed that are in a RuleSet other than those checked. The Tracer display does not identify gaps caused by this restriction.

The four or five RuleSets listed last are base Process Commander RuleSets. You can select them for tracing, but this may cause the Tracer to produce large quantities of output. You can trace flow rules (of flows in your application RuleSets) without selecting the Pega-ProCom RuleSet or other base RuleSets.

Your selections for RuleSets you select do not affect Tracer output for when rules. If you selected the When rules End option (in the Events to Trace group), Tracer shows the outcome of every when rule you execute, in any RuleSet.

By default, the Tracer displays the 500 most recent trace lines. You can set a higher value; this requires additional workstation memory.

As initially installed, each Tracer session uses a file buffer that holds up to 500 events not yet processed for display. Some complex tracing situations reach this limit; additional events are discarded. The following message appears:

Event queue is overflowing on server, events will be discarded.

To avoid this limitation, select fewer RuleSets or event types and then repeat the operation.

If this occurs often, you can increase the limit of the file buffer, which can contain many more events. See Tracer — Adjusting the file buffer size. If the problem persists after you have set a large buffer size, your application may contain an infinite loop.

Various conditions can cause the event queue to fill up. For example, if the Tracer and the traced requestor session are running on one client workstation, then both sessions share the normal limit of two HTTP operations to the server.  If the traced operations involve many HTTP operations, then the Tracer contends with other browser operations for access to the server.  This contention can cause the Tracer to drain the event queue more slowly, causing an event queue overflow.