Cache Settings

Use this section to specify how to handle caching at your site. Enabling caching on the application server improves performance, but you need to review the available cache options and determine which option best suits your site.

Note: The majority of the cache settings need to be uncommented in the PSAPPSRV.CFG file.

With EnableServerCaching, you specify what objects the system stores in cache on the application server. To enable application server disk caching the value must be set to 1 or 2.

If you enter 1 the system caches only the most used classes of objects, and if you enter 2, the system caches all object types regardless of the frequency of use. Which option you select depends on internal testing at your site.

To disable application server caching, set this value to 0. In most cases there is no reason to disable server caching. Doing so significantly degrades performance, because it requires the application server to retrieve an object from the database each time the system needs it.

This setting is the location where cache files will be written and stored for this domain.

Note: You must preload your shared cache before you enable shared caching on the application server.

Application Engine processes are independent from application server domains, directories, and configuration files. Therefore, Application Engine processes do not share cache with application server domain processes.

Caching enables the system to store definitions locally on the application server, eliminating unnecessary trips to the database server. If caching were disabled, the system would need to retrieve definitions from the database with each request, every time. This adds significant overhead to each transaction and affects system response times.

If server caching is enabled on the application server, which is usually the recommended approach, there are two modes of caching from which to choose.

Cache Mode

Description

Non-shared cache

By default, non-shared cache mode is enabled (ServerCacheMode set to 0).

With the non-shared cache mode, each server process that starts within a domain maintains its own separate cache file.

For example, assume you had two PSAPPSRV processes configured in a domain. In non-shared cache mode, there is one cache directory per PSAPPSRV server process, which each individual PSAPPSRV process uses separately.

In this case, you can find the cache files in PS_CFG_HOME\appserv\domain\cache\PSAPPSRV_1and \PSAPPSRV_2.

While the cache directories will grow over time to include the most used definitions, you have the option to preload the non-shared cache directories with the most used system definitions.

See Configuring an Application Server Domain to Preload Cache.

Shared cache

To set shared caching for the domain, enter 1 at the Set ServerCacheMode prompt. With this option enabled, you can find the cache files in PS_CFG_HOME\appserv\domain\cache\share.

The system assumes that a preloaded cache exists in the share directory. The preloaded cache contains most instances of the managed object types that are cached to file. When you boot the application server, if shared cache files are enabled but no cache files exist in the expected location, the system reverts to unshared caching.

To preload shared cache, you run delivered Application Engine programs that build your shared cache.

See Load Application Server Cache.

PeopleTools stores metadata in a memory cache on the server machine to increase system performance. However, in rare situations if the memory cache becomes too large, it can reduce the amount of memory available to other processes running on the server, which can degrade general performance. Use the MaxCacheMemory setting in certain situations where it is required to specify the maximum allowable size of the memory cache.

Note: Typically, this setting only needs to be implemented in rare circumstances, or when instructed to do so by GCS support staff. In most situations, it is recommended that sufficient memory be installed on the server machine to ensure optimal performance.

The MaxCacheMemory setting enables you to establish a size limit in megabytes, that the memory cache should not exceed. Every time the system retrieves an object from the database, such as a page, it updates the object’s LastUsedDate value. When your system reaches the memory cache threshold controlled by the MaxCacheMemory setting, the system "prunes“ the oldest objects in the memory cache until the desired memory cache size is reached.

Note: If a memory cache limit has been set, the system prunes the memory cache to keep it roughly 10% below the specified limit.

The default value of this setting is 0 (disabled), which disables memory cache pruning altogether, allowing for an unlimited memory cache. That is, when MaxCacheMemory is set to 0, the system continues to store a memory cache, but the system will not attempt to prune or reduce the size of the memory cache.

The default setting (disabled) might not be optimal for your application. You can adjust this setting to achieve the best trade-off between speed and available memory based on your system requirements. If you are in a situation where you need to limit the size of the memory cache, enter that limit in megabytes. Make sure to test your memory cache limit thoroughly in realistic scenarios, reflecting your production environment.

If enabled, the metadata (cache) is accessed from database, rather than the file system.

To implement database caching, uncomment the parameter and enter Y to enable database caching, orN to disable database caching. After changing this parameter, the domain does not need to be reconfigured.

The database cache is shared by all domains that enable this option.

When database caching is enabled, these settings are ignored:

  • EnableServerCaching

  • ServerCacheMode

  • CacheBaseDir

You can load the database cache using the Load Application Server Cache utility or the preload cache utility.

Note: Database caching is also available for Process Scheduler domains.

If you have created a cache project, specify the project name. Before booting a domain, you have the option to preload the cache, and this option creates the cache based on the load project you specify.

If database caching is enabled, the cache is preloaded into the database.

Set to Y to enable the cache repair utility, which can be configured using these settings:

  • AdjustMaxCacheMem

  • ExcessivePruningThreshold

  • CacheMissThreshold

  • MaxRepairCollection

If set to N, the cache repair utility does not run, and the system ignores these settings.

The cache repair settings enable you to configure the system to monitor and adjust automatically a domain’s cache while it runs, requiring no intervention from system administrators, and without requiring the domain or a server process to be restarted.

Note: When cache repairs occur, the system writes a message to the log file. The messages are preceded with the text “Cache Repair:” so they can be identified easily. The system begins recording these messages when the log fence is set to 4.

AdjustMaxCacheMem only applies if the MaxCacheMemory setting has been enabled for the domain. MaxCacheMemory is used to remove (also referred to as pruning) old objects from the memory cache so that it does not become too large and consume more system resources than expected.

Set the number of megabytes by which the system can increase the MaxCacheMemory setting if the memory cache size has reached the MaxCacheMemory setting. So, rather than pruning more objects from the memory cache, this setting increases the memory cache limit incrementally. For example, if MaxCacheMemory is set to 50 and AdjustMaxCacheMem is set to 5, the system increases MaxCacheMemory to 55 megabytes when the 50 megabyte limit is reached.

Note: When the system increases the MaxCacheMemory value, the increase will not be reflected in the configuration file. When the application server domain recycles, it assumes the original MaxCacheMemory value set in the configuration file. You can review the log files to determine what the system automatically increased the MaxCacheMemory to prior to the recycle, and set the static value in the configuration file accordingly.

Expressed as a percentage and represents the percentage of objects fetched from the database or persistent cache during the service request (and therefore added to memory cache) that have also been pruned from the memory cache at the end of the service request. If more than 80% of the objects fetched during a service request are pruned at the end of the service request, then the system is over-pruning.

Once the threshold has been reached, the system adjusts the MaxCacheMemory limit by the AdjustMaxCacheMem value so that the system is not constantly fetching from the persistent cache.

When this occurs, a message appears in the logs similar to:

Cache Repair: Warning excessive pruning has been detected. 83 percent or more of cached items have been removed from memory cache. MaxCacheMemory may be set too low.

If AdjustMaxCacheMem is not set to 0, then the system also logs the following message:

Cache Repair: Adjusted internal MaxCacheMemory setting from 50MB to 55MB.

Threshold for the number of times an object is found to be invalid within the memory and persistent cache. Once this threshold is reached, the system deletes the object from both memory and persistent cache, forcing the object to be refreshed from the database.

The system tracks the types of cache separately. If the object is invalid only in memory cache, then it's only removed from there. But if the object is invalid in the persistent cache (file or database cache), then it's removed from memory and the persistent cache.

The log file message is similar to:

Cache Repair: PDM(VAT_OPTIONS_SBP/ENG) Found invalidated object in memory cache- Removed from memory
Cache Repair: PDM(VAT_OPTIONS_SBP/ENG) Found invalidated object in file cache- Removed from memory and cache
Cache Repair: PDM(VAT_OPTIONS_SBP/ENG) Found invalidated object in db cache- Removed from memory and cache

To keep track of various cache metrics, the system stores some caching information for automatic analysis to determine if corrective measures need to be taken. The default limitation for this storage is 5 megabytes. This data is not used for historical reporting or analysis, and it is used only by the system while a server process is running. Once the limit is reached, the system purges all cache tracking information.

The log file message is similar to:

Cache Repair: maxed out memory at 5MB, purging cache repair data