Summary

V5.2 includes a statistics-collection facility for those rule types that are assembled into Java. This facility counts executions of activities, flow rules, stream rules (harness, section, HTML, XML and so on),  and other rule types.

When a node is shut down, these statistics are saved as instances of the Log-RuleUsage class. Through reporting on the Log-RuleUsage class, you can identify the activities (or other rules-assembled-rules) that were most often executed on your system.

Update: Starting with V5.3, these statistics are collected by the Pega-RULES agent (rather than at shutdown), which periodically runs the standard activity Code-.RuleUsageSnapshot. See Understanding the Pega-RULES agent.

Suggested Approach

You can use the V5.2 statistics facility to obtain information that can help you assess performance, including:

• How many times a specific activity has been executed,
• Which rules have been executed most frequently (for those rule types which use rules-assembly )
• Which rules have multiple versions assembled and compiled (due to revisions, nodes, and differences in RuleSet lists)

Note that a high frequency-of-execution may not indicate a performance bottleneck, if there is a need for the high frequency and the rule executes quickly. On the other hand, it is not worth spending your time to "optimize" rules that may be slow but execute rarely and do not affect user response or productivity.

Each time you shut down a server node, the system accumulates statistics in instances of the Log-RuleUsage class. Saved instances of this Log- class are normally mapped to a dedicated table in the PegaRULES database named pr4_log_usage. To facilitate reporting, all properties of this class are exposed as columns. See the Developer Help System topic Working with the Shutdown Rule Usage facility for more information on this facility.

The key to a row of this table includes the node ID (a hash value) for the server, the Java class name of the assembled rule, and a snapshot identifier, typically shutdown. Statistics in each row include the pyUseCount property, counting how many times that rule was executed since the node was first installed.

Caution: In a busy production Process Commander system, this table may contain tens of thousands of rows, one for each rules-assembly rule that has ever been executed. To avoid unnecessary system demand, design reports to search and retrieve only the rows and columns you need.

Example 1. Find the activities executed most often

To find the activities that were executed most often, create a summary view rule similar to the following example:

The first criteria limits the report to the rows produced during the cumulative shutdown operation. The second criteria selects rows corresponding to compiled activities.

The pxFamilyName property corresponds to the generated Java class name. This name does not depend on the server node, RuleSet and Version, or circumstance. (The user's primary page context — not the Applies To class of the actual rule — appears as part of this property value.)

At the bottom of the Content tab, enter a Maximum Values value that is large enough to ensure all rows for activities are included in the report. (In the system used for this example, over 1,800 distinct activities were assembled and executed.) This may require some repeated test runs.

The resulting report shows statistics in alphabetical order by family name:

To find the most frequently executed rule, export this report to Microsoft Excel and sort by descending values of the Sum pxUseCount column.

The result identifies the activities that were most often executed. Ordinarily, internal Process Commander infrastructure (such as activities executed by the Pega-RULES agent) appear at the top of the list. If any custom activities — in your application's RuleSets — appear in the top 50 of this list, review them for best performance and assess why they are running so frequently.

Example 2: Find how many times a single rule has run

You can adjust the selection criteria to focus on one rule. Select those rows that contain an underscore followed by the Activity Name key part (converted to lowercase). Add up the pxUseCount values for the appropriate rows.

Example 3: Find rules that might be assembled too many times

The Count column in this report shows how many times rules assembly has occurred for a single pyFamilyName value. This count can increase in various ways.

If users Smith and Jones have identical RuleSet lists, do not have the ability to check out rules, and access the system through one server node, Smith can execute a Java class that was assembled and compiled earlier for Jones. However, the Count column on the summary view display will be 2 or more if

• Their RuleSet lists differ
• They use distinct nodes to access the system,
• The rule was updated
• Two rules have the same pyFamilyName value

Review any rows you find with a larger-than-average count, to identify potential RuleSet list differences that can cause multiple assemblies. Remember that the personal RuleSet (for checked-out rules) is part of a user's RuleSet list; each activity a person with Allow Checkout? selected has a unique RuleSet list.

Note

Don't confuse this Log-RuleUsage data — which cover only rules of those rule types that are converted to Java code — with Log-Usage data, a separate class which contains data for system and requestor performance.