Working with the Shutdown Rule Usage facility

Pega Platform maintains statistics about the number of executions since startup. The system holds these statistics as property values in the Log-RuleUsage class, with additional detail in the Log-RuleUsage-Details class. During system shutdown, the system writes instances of these classes to the PegaRULES database, for later review and analysis.

Reports about these shutdown statistics can be useful in understanding which rules execute most often, and which execute rarely or not at all.

Note: Log-RuleUsage data, which covers only rules of those rule types that are converted to Java code by rules assembly, is different from Log-Usage data, which covers system and requestor performance.

How it works

Pega Platform maintains statistics during operation, which are written to the PegaRULES database for later review and analysis during application server shutdown.

The rules assembly data presented by the Performance tool covers only your own requestor session. In contrast, these statistics cover all requestors of every type, with cumulative statistics since startup. This can be helpful in identifying the most frequently and least frequently executed rules (for those rule types that are assembled using rules assembly).

By "rule", this topic means "a Java class created by rules assembly". One Pega Platform activity named Alpha-Mort-.Recalculate might produce multiple rules, one for each variation in:

Primary page class at the time of assembly (for subclasses of Alpha-Mort-.)
Ruleset and version
Node
Ruleset list of the requestor

You can access these statistics with reports or database reporting tools, such as SQL Query Analyzer or Crystal Reports, operating with the pr4_log_rule_usage table.

Key

The value of the pzInsKey key property of a Log-RuleUsage is concatenated from three other property values:

pxClassName — always Log-RuleUsage
pxSystemNode — Node ID of the node from which the snapshot was captured
The full Java class name of the assembled rule, starting with a type.
pyLabel — The snapshot name, such as "shutdown"

The Java class name identifies the rule type. Three examples are:

DECISIONTREE.RA_DECLARE_DECISIONTREE_RULE_PARSE_DELIMITED_GETPROMPTKEY_362AD3D39240B644A4CFBE58EA5DA52E

RA_ACTIVITY_DATA_ADMIN_OPERATOR_ID_SAVEDEVELOPERPREFERENCESXML_0C4D9291362765E0470388C76C1FD527

RA_HTML_FRAGMENT_SMARTPROMPT_NOINPUT_1EF7F65A6B1B426D7A6E5A270B8DF4DD!

To select rows from a specific node, restrict reporting to those Log-RuleUsage instances that match a fixed pxSystemNode value.

Unlike most other concrete classes derived from the Log- base class, the pxCreateDateTime property is not part of the key of the Log-RuleUsage class.

Statistics

The following properties are of primary interest in each snapshot row. All statistics are since startup of a node or since installation, covering all requestors of all types.

Property	Description	More
pyLabel	Identifies the type of snapshot. The value "shutdown" is reserved.
pxClassName	Full Java class name for the rule-assembled rule.	rules assembly
pxFamilyName	Rule type concatenated with visible key, converted to lowercase characters and converting special characters to underscore characters. For example: `activity_code_pega_list_inuserdesktop`
pxLastUse	Date and time that the rule was last executed.
pxNumPeeks	Number of times the class loader checked to see whether this entry was loaded.
pxNumInvalidate	Number of times the cache content was invalidated (unloaded), such that the next request forces rules assembly.	rules assembly
pxNumLoads	Number of times this class was loaded.
pxNumReload	Number of times this class was reloaded without forcing a rules assembly.
pxRuleCount	Number of dependences that this rule has.
pxCreateDateTime	First date and time this rule was captured by this snapshot.
pxUpdateDateTIme	Most recent date and time this rule was captured by this snapshot.
pxSize	Size of the Java CLASS file in bytes.
pxSystemNode	Node ID (hash) on which this snapshot was captured.	Node ID
pxUseCount	Number of times this rule was requested from the cache.

No automatic processing purges rows of the pr4_log_usage table. If your system has been shut down more than once, statistics for pxNumInvalidate, pxRuleCount, pxUseCount, pxNumReload, pxNumPeeks, pxNumLoads are cumulative since installation. Statistics for pxUpdateDateTime, pxLastUse are from the most recent shutdown.

prconfig.xml settings

Two prconfig.xml settings control this facility. The default values are:

<env name="usage/rules/shapshotonshutdown" value="true" /><env name="usage/rules/committhreshold" value="100" />

To disable this facility, update the prconfig.xml file to set the value of the shapshotonshutdown setting to false. To change the number of rows added during shutdown before a database commit operation, revise the value for the committhreshold parameter.

Note: As an alternative to updating the prconfig.xml file, you can use Dynamic System Settings to configure your application. See Dynamic System Settings data instances.

On a larger system with thousands of rules in use, set a larger committhreshold value to reduce the shutdown delay.

In the normal table mapping, the system saves these statistics a row of the pr4_log_rule_usage table.

Using the System Management Application, you can review these statistics since startup while the system is up, rather than at shutdown, by clicking the applicable node.

If desired, you can save interim snapshots of most of these statistics as instances of the Log-RuleUsage class. Run the standard activity Log-RuleUsage.TakeSnapshot, and enter as parameter a snapshot identifier (other than the keywords "shutdown" and "recent", which are reserved). To simplify later retrieval and reporting, enter a snapshot identifier that indicates a date or date and time, such as DEC212006NOON. Unlike the shutdown snapshot, rows of this snapshot contain statistics accumulated since the most recent startup, that is, not consolidated with older snapshot values.