Tracer
Setting options

Click the Settings button to set or adjust Tracer output options. Click  OK  when your entries are complete.

Determine events and event types to trace

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.

Set break conditions

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

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

Set General Options

Three settings affect the quantity of output from specific conditions:

Select the event types to trace

Complete the middle portion of this form to trace the progress of various events that occur in the system. Examples of rules that produce events are flows, declarative rules, and decision trees rules. You can also trace events related to services and database operations.

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

Tracing other events

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

1. Modify the activity (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 checkbox 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 checkbox that appears.
3. Click  OK   to close the Options panel.
4. Begin the operation you want to debug.

Select the RuleSets to be traced

This panel lists all RuleSets you can access, in the order they appear in your RuleSet list. B-18715 SR-2633

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 Pega- RuleSets listed last are base PRPC RuleSets. You can select them for tracing, but this may cause the Tracer to produce large quantities of output. C-428 You can trace flows (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. 2/4/08

Pages to Trace

By default, the Tracer tracks the primary and step pages for a requestor. Because sometimes activities modify pages that aren't the primary or step page, you can use this field to trace events on such pages. v62sp2 by GAJNJ

When the Abbreviate Events checkbox in General Options is selected, the Pages To Trace feature is disabled.

As your Tracer session runs, the Tracer watches these pages. If it locates the pages, links to their content are displayed in the Properties on Page window when you open an event from the Tracer output.

While there is no limit to the number of pages you can enter here, the Tracer runs slower as the number of traced pages increases.

User Interface — Set the number of lines to display

By default, the Tracer displays the 500 most recent trace lines. You can set a higher value; this requires additional workstation memory. If you only want to obtain the Tracer output as an XML file and save it to your local system, set this value to zero (0). Setting this value to zero also reduces the network and workstation load.

Avoiding event queue overflows

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.

Using the Tracer