You are here: Reference > Tools, accelerators, and wizards > Tracer > Tracer - Setting options

Setting options

Click Settings 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, select one or more Events to Trace check boxes. These options are most relevant to debugging activities (rather than flows or declarative rules).

Select the check boxes that identify the events of interest.

Events to Trace

Description

Access Deny rules

Select to display a line at the start of each execution of an Access Deny rule.

Activities Start Select to display a line at the start of each activity execution.
Activities End

Select to display a line at the completion of each activity execution.

Activity Steps Start

Select to display a line at the start of every activity step and step iteration.

Activity Steps End

Select to display a line at the completion of every activity step.

Data Transforms Start

Select to display a line at the start of each data transform execution.

Data Transforms End

Select to display a line at the completion of each data transform execution.

Data Transform Actions Start

Select to display a line at the start of each data transform action.

Data Transform Actions End

Select to display a line at the completion of each data transform action.

Exception

Select to cause the Tracer to display a line for every Java exception. In most cases, processing continues after the exception.

When Evaluations Start

Select to display a line at the start of every when condition evaluation, including preconditions and transitions.

When Evaluations End

Select to display a line at the completion of every when condition evaluation, including preconditions and transitions. If selected, Tracer output shows the results of all when rule executions from all rulesets, regardless of your selected rulesets.

Data Transforms Start

Select to display a line at the beginning of every data transform execution.

Data Transforms End

Select to display a line at the end of every data transform execution.

Set break conditions

To cause the Tracer to stop for specific events, select the Break Conditions check boxes. You can use the Tracer tool's Breakpoints 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:

Break Conditions

Description

Exception

Select to stop the Tracer upon the first Java exception.

Fail Status

Select to pause processing automatically when a step ends with a Fail status in the pxMethodStatus property value.

Warn Status

Select to pause processing if a step ends with a Warn status in the pxMethodStatus property value.

Set general options

Three settings affect the quantity of output from specific conditions:

Option

Description

Expand Java Pages

If the processing involves properties of mode Java Pages, select this check box to include the Java class details from those properties in the Tracer output. Using this option can significantly slow processing.

Abbreviate Events

Operating the Tracer can impact performance of your requestor session. Select to reduce the performance impact, by limiting the amount of clipboard detail retained for each row in the Tracer display. See Tips and notes.

Local Variables

Select to capture status of local variables for Begin and End events of activities and their steps. An output row is created in the Tracer output each time the value of a local variable in an activity is set.

Note: When the Abbreviate Events check box in General Options is selected, the Pages To Trace feature is disabled.

For some types of local variables, their values can be a Java null. For those cases, the Tracer output displays the string null - No Value for the value of the local variable.

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 declarative network — the forward and backward chaining computations that occur automatically.

Label

Description

Event Type

Optional. Enter an additional event type as instructed by Pegasystems Global Customer Services. Then click Add to enable tracing for this type.

For example, enter CaseType in the Add field to trace Case Type rules.

To remove an event type added to the list, enter its name and click Remove.

ADP Load

Trace the background thread (requestor) that loads a declare page asynchronously.

Adaptive Model

Trace Adaptive Model executions (part of DSM).

Alert

Alert log messages produced by your Thread in the Tracer output.

Asynchronous Activity

Trace asynchronous activity.

Auto Populate Properties

Trace the execution of auto-populated properties.

CaseType

Trace case type rule calculations. (To add this option, enter CaseType in the Event Type field and click Add).

DB Cache

Shows hits and misses for the rule cache and the conclusion cache.

DB Query

Show each SQL query sent to the PegaRULES databases and their results, including expansion of the BLOB column.

Data Pages

Show data page activity, including instantiations from properties, calls to data sources, and responses to those calls.

Declare Collection

Trace collection rules.

Declare Constraint

Trace Constraints rules.

Declare DecisionMap

Trace map values (start only).

Declare DecisionTable

Trace decision tables (start only).

Declare DecisionTree

Trace decision trees (start only).

Declare Expression

Trace Declare Expression rules.

Declare Index

Trace Declare Index rules.

Declare OnChange

Trace Declare OnChange rules.

Declare Trigger

Trace Declare Trigger rules.

Flow

Trace a flow execution. Rows of the Tracer output identify each flow start and end, each flow shape start and end, and the connectors (arrows on the flow diagram).

Interaction

Start and end of a user interaction, as defined by the Performance tool.

Linked Page Hit

Trace operations on linked pages that cause retrieval of the target page, from a cache. See Property form — Completing the General tab — Value modes.

Linked Page Miss

Record cache misses for linked properties. See Property form — Completing the General tab — Value modes.

Locking

Trace locking operations. Tracer output shows each lock acquired and each lock released.

Log Messages

Record each execution of the Log-Message method that has the SendtoTracer parameter selected.

Parse Rules

Trace Parse XML, Parse Structure, and Parse Delimited rules. Other parse rule types are not traced.

Predictive Model

Trace predictive model rule executions (part of DSM).

SOAP Messages

Trace detailed SOAP request and response messages for SOAP, SAP and .NET connectors and services.

Scorecard

Trace scorecard rule executions (part of DSM).

Services

Trace service rules and service activities. See Tracer — Tracing services.

Strategy

Trace strategy rule executions (part of DSM).

Stream Rules

Trace execution of all types of stream rules.

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

Select the rulesets to be traced

This panel lists all rulesets that you can access, in the order they appear in your ruleset list.

To trace the execution of rules in a specific ruleset, select the corresponding check 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 selected. The Tracer display does not identify gaps caused by this restriction.

The Pega- rulesets listed last are base Pega Platform rulesets. You can select them for tracing, but this may cause the Tracer to produce large quantities of output. 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.

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.

Note: When the Abbreviate Events check box 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.

Label

Description

Page Name

Enter a page name and click Add. Page names are case-sensitive.

To remove a page from the list, select it and click the Delete icon.

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.

Label

Description

User Interface  
Max Trace Events to Display

Enter the number of lines to display. When Tracer output reaches this limit, the oldest lines are dropped to allow newer lines to appear.

Changes to this limit take effect the next time you start the Tracer tool.

This feature is unrelated to and independent of the file event limit, which applies to unprocessed events — events not yet displayed.

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