Click Settings to set or adjust Tracer output options. Click OK when your entries are complete.
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. |
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:
Three settings affect the quantity of output from specific conditions:
Option |
Description |
| Expand Java Pages |
If the processing involves properties of mode |
| 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 |
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 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 |
| 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. |
As an advanced debugging technique, you can add custom events to Tracer output as follows:
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)
Debug in the Event Type field. Click Add.By default, the Tracer does not report changes to reference properties. To enable tracing of such changes:
Reference Properties in the Event Type field. Click Add.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.
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. |
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. |
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.