|
Tracer
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.
Events to Trace |
Description |
| Exception | Select to cause the Tracer to display a line for every Java exception. In most cases, processing continues after the exception. |
| 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. |
| When rules Start | Select to display a line at the start of every when condition evaluation, including preconditions and transitions. |
| When rules 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, check the Break Conditions checkboxes. 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:
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 checkbox 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.
For some types of local variables, their values can be a Java |
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.
Label |
Description |
| Event Type |
For example, enter To remove an event type added to the list, enter its name and click Remove. |
| Log Messages |
Record each execution of the Log-Message method that has the SendtoTracer parameter selected. |
| Alert |
Alert log messages produced by your Thread in the Tracer output. |
| 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). |
| Declare Constraint |
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 |
| Declare DecisionTree |
Trace decision trees (start only) |
| Declare DecisionTable |
Trace decision tables (start only) |
| Declare DecisionMap |
Trace map values (start only). |
| Declare Collection |
Trace collection rules. |
| Predictive Model |
Trace predictive model rule executions (part of DSM) |
| Scorecard |
Trace scorecard rule executions (part of DSM) |
| Strategy |
Trace strategy rule executions (part of DSM) |
| Adaptive Model |
Trace Adaptive Model executions (part of DSM) |
| Locking |
Trace locking operations. Tracer output shows each lock acquired and each lock released. |
| DB Query |
Show each SQL query sent to the PegaRULES databases and their results, including expansion of the BLOB column. |
| DB Cache |
Shows hits and misses for the rule cache and the conclusion cache. |
| Services |
Trace service rules and service activities. See Tracer — Tracing services. |
| Stream Rules |
Trace execution of all types of stream rules. |
| Parse Rules |
Trace Parse XML, Parse Structure, and Parse Delimited rules. Other parse rule types are not traced. |
| Interaction |
Start and end of a user interaction, as defined by the Performance tool. |
| Auto Populate Properties |
Trace the execution of auto-populated properties. |
| 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. |
| CaseType | Trace case type rule calculations. (To add this option, enter CaseType in the Event Type field and click Add). |
| Async DP Load | Trace the background thread (requestor) that loads a declare page asynchronously. |
Tracing other events
As an advanced debugging technique, you can add custom events to Tracer output as follows:
- 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 thePegaRULES Utilitieslibrary. Because this function returnsvoid, 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)
- Start the Tracer tool and then click the Options button.
- In the Options panel, enter
Debugin the Event Type field. Click Add . - Select the Debug checkbox that appears.
- Select the RuleSet referenced by the function call.
- 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:
- Enter
Reference Propertiesin the Event Type field. Click Add . - Select the Reference Properties checkbox that appears.
- Click OK to close the Options panel.
- 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.
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. 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.
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.
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 |
. 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