Back Forward Working with the Rules Assembly cache

 

The Rules Assembly cache is an in-memory table that allows PRPC to rapidly identify compiled Java CLASS files that correspond to compiled and assembled rules (such as activities, functions, and stream rules).

The cache operates automatically and invisibly, and only a few configuration settings affect its operation. However, understanding the cache and the causes of rules assembly processing can be helpful in achieving good system performance.

Virtual Rules Table (VTable)

7.1 introduces a higher performance replacement for Application-Based-Assembly (ABA) and Rules Assembly (RA), Virtual Rules Table (VTable). VTable significantly reduces the amount of assembly done in the system in response to rule changes. VTable is entirely automatic - the only configuration option is to disable it, which makes it fall back to ABA.

VTable is automatically primed during system startup with rules that have been either statically assembled or built dynamically as the rules were used in the system.

VTable does detect the PEGA0037 alert described below.

Application-Based-Assembly (ABA)

The similar Application-Based Assembly (ABA) cache can provide higher performance for those applications that meet certain restrictions on RuleSet use. Use of the ABA cache is recommended when feasible. See Understanding Application-Based Assembly mode.

Basics

When a requestor needs to execute an activity (or another rule that PRPC assembles into Java upon first use) that is already compiled, the system loads the compiled code from disk (if necessary) and executes it promptly.

However, when there is no such compiled version (reflecting the user's current node and RuleSet list), the system must generate, compile, and save the Java code before it can execute it. This can be done "on-demand" when the rule is first used, or in advance, through the static assembler.

In a production setting where rules change rarely and the same rules are executed repeatedly, the rules cache can have a high hit rate with few rules needing to be assembled and compiled on first use. In a lightly used system with many developers, frequent rule changes, and many rules checked out, the hit rate is likely to be lower, and significant system resources will be used.

Each entry in the rule assembly cache is represented by an instance of the Java class FUAEntry. By default, the Rules Assembly cache contains up to 20,000 entries, speeding access to the Java CLASS files. Though rarely needed, you can change this limit with a prconfig.xml setting:

<env name="fua/global/instancecountlimit" value="nnnnn" />

As an alternative to the prconfig.xml file, you can use Dynamic System Settings to configure your application.
See How to create or update a prconfig setting.

Use the System Management Application to determine the current rule count and size in bytes of the Rules Assembly cache.

  1. From the Designer Studio, start the System Management Application usingSystem > Tools > System Management Application. You may be prompted for a username and password.
  2. Select a node.
  3. Click Memory Management from the SMA left menu strip. In the right panel, locate the table row labeled Rule Assembly in the Caches group.

Additions and deletions

During normal system operations, each newly assembled rule is recorded as an additional entry in the cache. For each entry, the system records a use count (since startup), how many times the CLASS was loaded, and the date and time of the last use.

The system removes entries from the cache when a newer assembly compilation of the rule is required because the rule or another rule it depends on was modified.

Because of Java code inlining, one cache entry may support a few different actual rules, so the number of cache items may be lower than the actual number of rules that can be satisfied through the cache.

If the cache becomes full, the system purges entries with a low-use count to make room for additional entries. In addition, the Pega-RulesEngine agent purges some records daily.

When you update (or create or delete) a rule, it may "invalidate" one or more other rules present in the cache. A PEGA0032 alert occurs if updating a single rule invalidated more than 10 other rules, bringing your attention to a situation that can hurt performance by causing additional rules assembly. You can change this threshold.

Daily snapshot

Once each day, the Pega-RULES agent records a snapshot of the contents of the Rules Assembly cache, saving information into instances of the Log-RuleUsage and Log-RuleUsage-Details classes. (In the schema for the PegaRULES database, instances of these classes are saved as rows of the pr4_log_rule_usage and pr4_log_rule_usage_details tables, respectively.)

At the next startup, the system uses this snapshot information from the most recent day to reconstruct parts of the Rules Assembly cache. This process increases startup time but can provide a performance benefit by avoiding the need to reassemble and recompile rules that are already assembled and compiled from earlier system sessions.

Select > System > Tools > System Reports ... to access reports that summarize this data.

Cache priming at startup

When a PRPC server node shuts down (intentionally or unintentionally), the in-memory portion of the rule assembly cache is lost; the Java class files remain on the disk. To avoid having to reassemble all the cache entries, regenerate the Java code, and recompile it (as though the rules had never been executed), PRPC uses the Java class files to recreate a portion of the most heavily used cache entries. This capability is especially useful during peak load periods when resource demands are at their greatest.

When a server is restarted, the system:

  1. Gathers usage statistics from the most recent snapshot in the Log-RuleUsage class for the node being restarted.
  2. Creates a list of rules that have changed since the snapshot to eliminate Java classes whose input rules may have changed.
  3. Calculates the maximum number of Java classes to reload based on the value set in instancecountlimit, loads unchanged Java class from disk based on the usage statistics, and finds instances from Log-RuleUsage-Details.
  4. Creates new FUAEntry instances in the cache using each discovered detail row, up to 10% of the cache size (so by default up to 2000 entries are added during the startup-priming).
  5. Rebuilds cache entries that were not recreated (changed after the snapshot, for instance). Each of the new entries is qualified by the user's RuleSet list and server node. For example, if user A has executed and cached a rule in her RuleSet list, and User B has executed the same rule but changed it after the snapshot, the rule in User B's list must be reassembled and re-cached when it is executed.

If the latest snapshot is more than 48 hours old, it is not considered a valid basis for cache-priming, and cache priming does not occur.

This cache-priming capability is enabled by default. If necessary, you can disable it by following these steps:

1. Update the prconfig.xml file to contain the line:

<env name="fua/enablereload" value="false" />

2. Stop and restart or redeploy the system.

As an alternative to the prconfig.xml file, you can use Dynamic System Settings to configure your application.
See How to create or update a prconfig setting.

When disabled, the system creates new cache entries when a user calls a rule (reflecting the user's current node and RuleSet list), which generates, compiles, and saves the Java code before executing it.

Static Assembler

The static assembler is a command- line utility used to assemble certain rules within a specified application.

It may be beneficial to run the static assembler after importing an application that contains a large number of rules. Pre-assembly improves the response time for interactive users after system startup. For more information about the static assembler utility, the PDN.

PEGA0037 alert

Any rule that requires more than 400 milliseconds to assemble produces a PEGA0037 alert in the alert log. This may indicate that the rule is unusually complex, or may indicate other performance issues.

If the 400 millisecond threshold is not appropriate for your system, you can set a different value in the prconfig.xml file or Dynamic System Settings.

Rules assembly and performance

TipTypically, rules assembly processing occurs less often in a production system or in a system that has heavy use, because most of the time, users execute rules that are already assembled and compiled. However, in certain situations, even when rules change rarely, excessive rules assembly processing can affect overall system performance. To encourage greater reuse and sharing of already-assembled rules:

Definitions rules assembly, static assembler
Related topics Understanding the Pega-RULES agent
Understanding the Pega-RulesEngine agent
Understanding caching
How to identify the Java class that has exceeded the elapsed rule assembly threshold (PEGA0037 alert)
Working with the Shutdown Rule Usage facility
How to detect when a rule change invalidates entries in the Rules Assembly cache

UpSysAdmin category