The Rules Assembly cache is an in-memory table that allows the Pega 7 Platform 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.
The Virtual Rules Table (VTable) is a higher performance replacement for Application-Based-Assembly (ABA) and Rules Assembly (RA). 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 detects the PEGA0037 alert, which is described below.
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.
When a requestor needs to execute an activity (or another rule that the Pega 7 Platform 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" />
Note: 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.
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.
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 Designer Studio > System > Refractor>Rules ... to access reports that summarize this data.
When a Pega 7 Platform 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), the Pega 7 Platform 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:
instancecountlimit
, loads unchanged Java class from disk based on the usage statistics, and finds instances from Log-RuleUsage-Details.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.
Note: 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.
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.
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.
Typically, 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: