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)
| Metric | Description |
|---|---|
| Region | The name of the cache region. |
| Default Region | true if this cache region is using the cache chain for the Default Cache Region; false otherwise. |
| Configured | The maximum number of items this cache is configured to hold. |
| Size | The actual number of items this cache region is currently holding. |
| Load | |
| Hits | The 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 Rate | How 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. |
| Evictions | The 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)
| Metric | Description |
|---|---|
| Region | The name of the cache region. |
| Total Memory | The total memory used by the cache region (including all obects in this region). |
| Memory per Obect | The average memory used by each obect in this region. |
| Size | The number of items in this cache region. |
Additional Useful Cache Metrics (Calculated)
| Metric | How to Calculate |
|---|---|
| Utilization | Size / Configured |
| Eviction Rate | Evictions / 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.
