Understanding caching

• Rule cache — Per node. Reduces PegaRULES database traffic, contains copies of rules recently accessed or recently updated by developers. Occupies virtual memory. The PegaRULES agent, during the periodic system pulse, invalidates rules in the rule cache that were recently updated on another node.
• Application-Based Assembly cache — Per node, Tracks rules for which Java generation and compilation is complete. Also known as ABA or AppCentric cache.
• Rules Assembly cache — Per node. Tracks rules for which Java generation and compilation is complete. Formerly known as the FUA cache. Located in virtual memory; links to loaded Java classes.
• Rule Resolution cache — Per node. Supports faster rule lookup; in virtual memory.
• Lookup List cache — Per node. Contains the results of list view reports, such as used by the Application Explorer and Class Explorer.
• Static Content cache — Per node. Compressed text and image files on disk corresponding to extracted binary file rules and text file rules. Contains a subdirectory for each RuleSet list. Supports ordinary HTTP serving.
• Personal rules cache — Per node. Similar to the Rules Assembly cache, for rules checked out into personal RuleSets by developers.
• PegaRULES database cache — System-wide. Provided by Oracle, Microsoft SQL Server or other database software, not by PRPC software. This can be an important factor in performance, but managed independently of PRPC server caches.
• Conclusion cache — Similar to rule cache, for field value rules and a certain properties; also called the dictionary cache.
• Browser cache — On each user's workstation; for Internet Explorer, also known as Temporary Internet Files.
• String pool cache — Reduces memory requirements
• Declarative pages cache — Holds the contents and status of those declarative pages that have a node-wide scope.
• Declarative Networks cache — Supports declarative processing.

For more information about these caches, search the PDN for Rule Caches (May 2006), a PDF document.

Use the System Management Application to learn the current count and size in bytes of the rule cache, rule assembly cache, declarative pages cache, and conclusion cache. From the Designer Studio:

1. Start the System Management application using > System > Tools > System Management App. You may be prompted for a user name and password.
2. Select a node.
3. Click the Memory Management link in the left panel. Locate the Caches group in the right panel.

Basics

PRPC maintains a memory cache of recently found (and non-found) rules to improve the performance of the engine, especially during rule resolution searches. This rule cache (also called the rule instance cache) operates invisibly and automatically. The system adds to the cache any rule that is read three or more times (for some rule types, a higher limit applies). Caching provides a substantial performance and response time improvement for all users.

Instances of most concrete classes other than those derived from the Rule- base class are not cached in the rule cache.

In a multinode cluster, a rule recently updated by a user on one node can also be present (and stale) in the rule cache of another node. During system pulse processing, the Pega-RULES agent on each node clears such stale rules from the rule cache.

Access to the rule cache is supported by a separate identity index, linking the family names of rules to the individual rules in the rule cache. (The family name

In older releases, the rule cache was sometimes called the instance cache, database cache, or system cache.

Assessing performance of the rule cache

For your own requestor session, the Performance tool display contains statistics on the use of this cache, in the Database Access Counts area.

For a statistical overview of rule cache performance on the node since startup, select Advanced > Rule Cache Management from the System Management application menus.

Rule cache size and purging

Initially, the rule cache limit is 3,000 entries. This count includes rules on "probation". Probationary entries contain only keys and usage counts, rather than the full rule content. If this cache limit is approached during system operations, older entries are discarded automatically to make room for newer entries, following the Most Recently Used (MRU) algorithm.

You can change this limit by adding a prconfig.xml setting similar to:

<env name="cache/instancecountlimit" value="nnnnn" />

Memory consumed by this cache is not available for other JVM operations. To see the size in entries and bytes of this cache, select > System > Tools > System Management Application, select a node, and click the Memory Management menu item. Look for the row labeled Rule Instance in the Cache grouping.

When required in special situations, your activity can call the PublicAPI function PRThread.setCacheEnabled(false) to disable rules caching temporarily for the current requestor.

Introduced in V6.3, the ABA cache operates similarly to the Rules Assembly cache. It identifies rules for which rules assembly on the current node is complete. Each rule that generates Java and executes is a candidate for the cache. The system saves the generated Java code and the compiled Java code on disk in the temporary files directory.

The Rules Assembly cache identifies rules for which rules assembly on the current node is complete. Each rule that generates Java and executes is a candidate for the cache. The system saves the generated Java code and the compiled Java code on disk in the temporary files directory.

By default, the Rules Assembly cache is limited to 20,000 entries. If this limit is approached during system operations, older entries are discarded automatically to make room for newer entries, following the Most Recently Used (MRU) algorithm. The system records this situation in the Alert log as a PEGA0016 or PEGA0017 alert. You can change this limit by adding a prconfig.xml setting similar to:

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

Memory consumed by this cache is not available for other JVM operations. Memory consumed by this cache is not available for other JVM operations. To see the size in entries and bytes of this cache, select> System > Tools > System Management App,, select a node, and click the Memory Management menu item. Look for the row labeled Rule Assembly in the Cache grouping.

If rules assembly occurs often on a production system (when few rules are being modified), the Rules Assembly cache may be too small.

Periodically — at system shutdown and once each 24 hours — the system records statistics about the contents of the Rules Assembly cache in instances of the Log-RuleUsage and Log-RuleUsage-Detail classes. This information is normally used at the next system startup to "prime" the Rules Assembly cache during the next system startup, so that it doesn't start empty. See:

• Working with the Shutdown Rule Usage facility
• Working with the Rules Assembly cache
• How to detect when a rule change invalidates many entries in the Rules Assembly cache.

The Rules Assembly cache, personal rules cache, PropertyReference cache, and two minor caches (LowerCase and UpperCase) each have a target size, measured by record count, of approximately three-fourths of the maximum size.

For example, the default maximum size of the Rules Assembly cache is 20,000 items, so the default target size is about 15,000 items.

When PRPC detects that a cache has reached the target size, the system adds a PEGA0016 alert message to the Alert log, and allows older records in the cache to become invalidated (replaced as needed by newer records).

When PRPC detects that a cache has reached the limit specified in the prconfig.xml file (or a default limit if none is specified), the system adds a PEGA0017 alert message to the Alert log, and forcibly deletes the oldest records in the cache until the target size is reached. For example, about 5,000 older rules are purged from a Rules Assembly cache containing 20,000 items. Additions and updates to the cache are temporarily blocked from during the purge operation.

If your Alert log contains many PEGA0016 or PEGA0017 alerts, investigate the size limit for that cache and analyze possible causes. You can increase the limits by changing the prconfig.xml file, but that reduces JVM memory available for other system processing.

See PDN Article 25354 Understanding the PEGA0017 Alert.

Static content refers to information that can be extracted once from a rule to a HTTP server or Web server and thereafter is unaffected by use of an application, the contents of user clipboards, and so on. PRPC stores static contents for these rule types:

• Binary file rules (Rule-File-Binary rule type, for images, such as JPG files)
• Text file rules (Rule-File-Text rule type, for JavaScript and Cascading Style Sheet files)
• Form file rules, for rule forms (Rule-File-Form rule type)
• eForm file rules (Rule-File-eForm rule type, for PDF forms)

Each directory below the StaticContent directory contains extracted static content; the directory name encodes the exact RuleSet list that the content belongs to. To minimize storage, PRPC creates directory names with on a hash code derived from an entire RuleSet list. So, the file system can contain many different files named CompanyLogo.jpg. Which CompanyLogo.jpg file that a user receives for display in a browser session depends on that user's RuleSet list.

Use the System Management application to delete all the static content extracted on the current node. Alternatively, you can delete the extract marker file to cause the system to clear the static content directories at the next startup.

The location of the StaticContent directory is determined by a temporary files path setting in the prconfig.xml file.

RuleFileServlet servlet

The RuleFileServlet servlet locates and "serves" the correct version of a static content file to a user. If the static, extracted file has never previously been referenced, this servlet first extracts the file from the rule, and then converts images and other binary files from Base64-encoding to the normal file format.

HTTP Compression

Through settings in the prconfig.xml file, PRPC supports HTTP compression of static files, to reduce HTTP message size and network demand. The HTTP/ServerGZIPEnabled setting (for UNIX) is enabled by default, meaning that compression occurs. If needed for debugging or other purposes, you can set the value of these settings to false to disable such compression.

A similar setting HTTP/ServerZIPEnabled setting for Windows servers is not enabled by default. If desired, add this setting with value="true":

<env name="HTTP/ServerZIPEnabled" value="true" />

PRPC automatically saves, as XML files on disk, the results of list view report called by certain standard activities. These form a cache of recent search results available for redisplay and reuse, if the same list is needed later. This collection of disk files is known as the lookup list cache, which exists independently on each node.

This cache significantly can reduce database searches and improve response times. If users ask for a list that is not present in the cache, the system:

• Executes the list view report
• Sends the results to the user's workstation for display
• And saves the results as an XML file in the lookup list cache

If system operations later invalidate the contents of a lookup list, the system automatically deletes the corresponding lookup list file. That lookup list is not regenerated until the next time it is requested.

The many standard activities named LookupList execute list view reports also named LookupList; details vary by Applies To class. These activities are often useful when you configure Dynamic Select controls.

In a multinode cluster, each server has a separate lookup list cache. Synchronization processing that occurs during the system pulse on each node can cause the lookup list cache on a node to be purged; its contents are then rebuilt as needed.

Clearing the lookup list cache from disk

Using the System Management application, you can clear this cache on a specific node. This is required only in rare, unusual situations.

1. Start the System Management application. You may be prompted for authentication credentials.
2. Select a node.
3. Select Advanced > ETier Static Content Management.
4. Click  Delete LookupList Cache .

Declarative pages

> System > Tools > System Management App

Personal cache

The personal rule cache operates similar to the rule assemble cache, but for checked-out rules. Like the rule assembly cache, the personal rule cache has a default limit of 20,000 rules.

You can change this limit by adding a prconfig.xml setting similar to:

<env name="fua/personal/instanceCountLimit" value="nnnnn" />

Conclusion cache

A conclusion is a saved instance of a generated Java object. Conclusions cached speed the runtime lookup of field value rules, class rules, property alias rules, and selected properties. The conclusion cache corresponds to instances of the System-CachedConclusion class, stored in the pr4_rule_sysgen table of the PegaRULES database.

Using the System Management application, you can review or clear the conclusion cache, though such clearing is needed rarely and only in response to specific symptoms. Choose a node, then select Advanced > Dictionary Cache.

To see the size in entries and bytes of this cache, select > System > Tools > System Management App, select a node, and click the Memory Management menu item. Look for the row labeled Dictionary in the Cache grouping.

Clearing this cache can seriously degrade performance until the contents are recached. Do not clear this cache unless advised by Pegasystems Global Support.

Declarative Network cache

This cache supports declarative processing. If instructed by Pegasystems staff, you can clear it with the System Management Application menu option Advanced > Declarative Rules Management > Clear.

Browser cache

To clear the Internet Explorer cache on a workstation:

1. Select Tools > Internet Options > General > Temporary Internet Files.
2. Select  Delete Files   and click  OK  .
3. To purge cached JavaScript files also, select  Delete All Offline Content  and click  OK  .

Safari and Firefox also provide menu options to delete browser cache contents.

By default, the HTTP messages sent from PRPC to a browser session have a cache-control setting of 24 hours (86,400 seconds). The prconfig.xml file element named http/defaultcachingtimeout controls this HTTP setting.