Cache Tuning documentation for the dotCMS Content Management System

dotCMS is designed to make full use of cache to improve performance and reliability. dotCMS attempts to retrieve from cache before accessing the database and provides multiple methods such as cache chains to enable sophisticated and responsive cache configuration for different sites and needs.

This document provides some very basic guidelines for evaluating your cache performance and tuning the cache for specific needs; however it is important to understand that the needs of every site and customer vary widely, and cache tuning - especially for large and sophisticated sites - is necessarily a custom process each and every time. If you would like assistance understanding and configuring the cache for your specific site, please contact dotCMS support or Professional Services for assistance.

Cache Metrics

Raw Cache Metrics

The Cache screen (System -> Maintenance -> Cache) provides detailed metrics for your cache on your dotCMS instance. These metrics provide information on how each of your cache regions, including the following:

Memory Cache (Caffeine, Timed Memory)

MetricDescription
RegionThe name of the cache region.
Default Regiontrue if this cache region is using the cache chain for the Default Cache Region; false otherwise.
ConfiguredThe maximum number of items this cache is configured to hold.
SizeThe actual number of items this cache region is currently holding.
Load 
HitsThe number of times an item has been successfully found in this cache region (preventing a fetch from the next cache region in the chain, or from the database).
Hit RateHow frequently an attempt to retrieve an element from this cache region succeeded, preventing a fetch from the next cache region in the chain, or from the database.
Load Time Avg.The average time to load an item from this cache region upon a successful hit.
EvictionsThe number of times an item has been “ejected” from the cache to make room for a new item. Items are only ejected from the cache when the cache is full (Size = Configured) and a new item is retrieved which is not currently in the cache.

Persistent Cache (Disk, Redis)

MetricDescription
RegionThe name of the cache region.
Total MemoryThe total memory used by the cache region (including all obects in this region).
Memory per ObectThe average memory used by each obect in this region.
SizeThe number of items in this cache region.

Additional Useful Cache Metrics (Calculated)

MetricHow to Calculate
UtilizationSize / Configured
Eviction RateEvictions / Hits

Cache Tuning Goals

There are many different ways to tune the cache, and both the methods used will vary depending on your site design, server capabilities, and need. Before you begin tuning your cache, it is important to make decisions about what results you wish to achieve, and to take appropriate steps to accomplish your specific goals.

Note also that you can not accomplish all goals at the same time. Achieving some goals will necessarily require changes that conflict with other goals; for example, reducing memory footprint is often incompatible with improving performance, and taking steps to reduce how much memory is used by your cache will almost always result in some reduction in performance. Therefore it is recommended that you choose only one goal if possible, and if you do choose two or more goals that you clearly define the priorities of which goal takes precedence.

Reduce Memory Footprint

If your server is running out of memory (or dangerously close to it), you may wish to reduce the amount of memory used by the cache.

  • Reduce the size of the cache regions which take up the most memory.
    • Note that, depending on the cache region and the size of the reduction, this may have a significant impact on performance.
    • In general, try to reduce the size of regions which contain a small number of large items (such as large files) and do not reduce the size of regions which contain a large number of small items (such as contentlets).
    • The greater the ratio of hits to evictions in a cache region, the greater the (negative) impact on performance will be by reducing the size of the cache region.

Reduce Disk Space Usage

Disk caches (including H22) do not have any controls to limit the amount of disk space they use.

  • Ensure that all cache regions have an in-memory cache (such as Caffeine or Timed Cache) in the cache chain before any disk cache.
    • Potential Trade-Off: Increase in memory footprint.

Increase Performance

Note: Cache tuning is only one of many ways to improve performance, and tuning the cache to improve performance will often require trade-offs to increase the memory footprint or disk usage of the cache. Please read the Performance Tuning documentation in full before tuning your cache for performance, and consider other methods to improve performance (which may not have the same trade-offs) before making changes to your cache.

  • Increase the size of cache regions which have a low [Hit Ratio](#MetricsCalculated}.
    • Potential Trade-Off: Increase in memory footprint.

Conditions to (((Look For)))

High Utilization and Low Hit Rate

High Evictions and Low Hit Rate

Low Utilization

You may be able to reduce the cache memory footprint by reducing the Size of the cache region.

Low Hit Rate