Confluence Docs 3.0 : Cache Performance Tuning This page last changed on Sep 01, 2009 by ggaskell. Confluence performance can be significantly affected by the performance of its caches. It is essential for the administrator of a large production installation of Confluence to tune the caches to suit its environment. There are several configurable parameters for each of the cache regions, most notably cache size, cache expiry delay and eviction policy. In the majority of the cases, cache size is the parameter you would want to change. Fortunately, from Confluence 3.0, it is very easy to adjust cache sizes through the Administration Console. However, if you need to modify parameters other than a cache size, you would need to modify the relevant configuration files manually.
| If you only need to modify Confluence's maximum cache sizes, you can do this through the Cache Statistics feature of the Administration Console.
The cache performance information for your Confluence installation is available under Administration > Cache Statistics. More information about the numbers displayed here is available on Cache Statistics. On this page: Cache tuning example Finding the configuration file Cache Key Mappings Standard Editions of Confluence Understanding the Ehcache Configuration File Converting your Coherence configuration to Ehcache Clustered Editions of Confluence Understanding the Coherence configuration file Defining Caching Scheme Mappings in Coherence Cache config file Important Caches Cache Tuning Follow-Up ## Cache tuning example As an example of how to tune Confluence's caches, let's have a look at the following table:
Caches | % Used | % Effectiveness | Objects/Size | Hit/Miss/Expiry
--- | --- | --- | --- | ---
Attachments | 87% | 29% | 874/1000 | 78226/189715/187530
Content Attachments | 29% | 9% | 292/1000 | 4289/41012/20569
Content Bodies | 98% | 81% | 987/1000 | 28717/6671/5522
Content Label Mappings | 29% | 20% | 294/1000 | 4693/18185/9150
Database Queries | 96% | 54% | 968/1000 | 105949/86889/83334
Object Properties | 27% | 18% | 279/1000 | 5746/25386/8102
Page Comments | 26% | 11% | 261/1000 | 2304/17178/8606
Users | 98% | 5% | 982/1000 | 6561/115330/114279
The caches above are of size 1000 (meaning that it can contain up to 1000 objects), which is the default size for caches in the default cache scheme. Refer to Confluence Cache Schemes for more explanation. You can tell when a cache size needs to be increased because the cache has both: a high usage percentage (above 75%) a low effectiveness percentage. Check the 'effectiveness' versus the 'percent used'. A cache with a low percent used need not have its size lowered; it does not use more memory until the cache is filled. Based on this, the sizes of the "Attachments", "Database Queries", and "Users" caches should be increased to improve their effectiveness. As the stored information gets older or unused it will expire and be eliminated from the cache. Cache expiry may be based on time or on frequency of use. There is not much that you can do with a cache that has both a low percentage of usage and effectiveness. Over time, as the cache is populated with more objects and repeat requests for them are made, the cache's effectiveness will increase. ## Finding the configuration file The caches are configured in `ehcache.xml` (for standard editions) or `confluence-coherence-cache-config-clustered.xml` (for clustered editions) which is stored in `<confluence-home>/config/`.
| Oracle Coherence Licensing Change: Due to a license agreement change between Atlassian and Oracle over the Coherence technology, from September 2009, Confluence will be made available in two editions: Standard Edition — Confluence with Ehcache's caching technology (available to customers with non-clustered Confluence licenses). If you are currently running a clustered installation of Confluence, please do not upgrade it with a standard edition of Confluence. Clustered Edition — Confluence with Oracle's Coherence clustering and distributed caching technology (available to customers with Confluence clustered licenses only). For more information about these changes, please refer to the Coherence License Changes document. If you have a Confluence clustered license, are running a clustered installation of Confluence and wish to upgrade to Confluence version 2.6 or later after late September 2009, please ensure that you download only a clustered edition of Confluence and please refer to the Confluence 3.0.1 Upgrade Notes for additional upgrade information.
## Cache Key Mappings The cache configuration file configures caches by their keys. When you move your mouse over the the cache names displayed on the cache statistics page, a tooltip will indicate the actual cache key for that cache name. Using our example from the table above, if we were to modify parameters for the `Users` cache we would need to change the cache with the key `com.atlassian.user.impl.hibernate.DefaultHibernateUser`. Do not get confused with `Users (External Mappings)` and `Users (External Groups)` which are in themselves, two separate caches. "Users" is the friendly name for `com.atlassian.user.impl.hibernate.DefaultHibernateUser`. ## Standard Editions of Confluence In standard editions of Confluence, the caching layer is Ehcache. #### Understanding the Ehcache Configuration File For more information about the Ehcache configuration file and a full reference on Ehcache configuration, please refer to the Ehcache configuration documentation. #### Converting your Coherence configuration to Ehcache
| This section only applies to customers who: Have an installation of Confluence that was downloaded before the 4th of September 2009. Intend to (or have already) upgraded to Confluence 3.0.1 or later (or to Confluence versions 2.6.3, 2.7.4, 2.8.3, 2.9.3 and 2.10.4). Will use a non-clustered Confluence license for the Confluence upgrade. Have implemented customisations to their Confluence installation's cache configuration file (`confluence-coherence-cache-config.xml`).
To maintain your existing cache configuration file settings, you will need to transfer any cache customisations you have implemented in the Coherence cache configuration file (`confluence-coherence-cache-config.xml`) to the relevant entries in the Ehcache cache configuration file (`ehcache.xml`). Each cache has a `cache-mapping` element in the Coherence file (of which there is an equivalent `cache` element in the `ehcache.xml` file). Unfortunately, copying across your customisations is not quite a straightforward process because the Coherence file defines several 'caching schemes' to store the actual cache values, which in turn are referenced by the `cache-mapping` elements. In contrast, the `ehcache.xml` file does not support caching schemes and a cache's values are expressed explicitly in separate parameters of a `cache` element. To convert your Coherence cache configuration file customisations across to the equivalent Ehcache file: Open both the `confluence-coherence-cache-config.xml` and `ehcache.xml` files in a text editor. These files are located in the `<confluence-home>/config` directory. If you implemented your customisations in a version of Confluence prior to 3.0, you will most likely find the `confluence-coherence-cache-config.xml` file in the `<confluence-install>/confluence/WEB-INF/classes` directory. In the customised `confluence-coherence-cache-config.xml` file: Identify the caching schemes that were customised in this file and make a note of the values of all its child elements. Typically, each caching scheme is located inside a `local-scheme` element and all of these are enclosed within the `cache-schemes` element, which appears towards the end of this file. Note each customised caching scheme by the content of its `scheme-name` element. For each `cache-mapping` element (which typically appears towards the top of this file), identify if it has a `scheme-name` element whose content matches one noted in the previous step and if so, make a note of its associated `cache-name` element. In the `ehcache.xml` file: Identify each `cache` element whose 'name' parameter matches the `cache-name` elements noted in step '2c'. Using the mappings table below, apply the values noted in step '2a' to the appropriate parameters of the `cache` elements identified in the previous step ('3a'). Mappings table showing how elements of the Coherence cache configuration file map to parameters of the equivalent Ehcache file.
Coherence Element | Ehcache Attribute
--- | ---
`high-units` | `maxElementsInMemory`
`expiry-delay` > 0s | `timeToIdleSeconds` - Use this attribute for expiry delays greater than 0s along with the `eternal` attribute set to 'false'
`expiry-delay` = 0s | `eternal` - For expiry delays of 0s, set this attribute to 'true'.
## Clustered Editions of Confluence #### Understanding the Coherence configuration file The Coherence configuration file is a mapping of cache keys to cache schemes. Each cache scheme controls the expiry, eviction policy and size of the caches linked to it. A cache scheme can extend another scheme. For a full reference, see the Oracle's Coherence cache configuration documentation. #### Defining Caching Scheme Mappings in Coherence Cache config file If a cache key does not have an explicit definition in the caching scheme mappings (defined in `confluence-coherence-cache-config.xml`) then it will use the "default" `cache-mapping`. In our example, `com.atlassian.user.impl.hibernate.DefaultHibernateUser` is not explicitly defined in the caching scheme mappings. Hence to increase the expiry-delay to 2 hours, we will need to define the mapping ourselves and add the following within the `<caching-scheme-mapping>...</caching-scheme-mapping>` tags:
    <cache-mapping>
    <cache-name>com.atlassian.user.impl.hibernate.DefaultHibernateUser</cache-name>
    <scheme-name>cache:com.atlassian.user.impl.hibernate.DefaultHibernateUser</scheme-name>
    </cache-mapping>
Then we will need to define a cache schema with name `cache:com.atlassian.user.impl.hibernate.DefaultHibernateUser` within `<caching-schemes>...</caching-schemes>` tags.
    <local-scheme>
    <scheme-name>cache:com.atlassian.user.impl.hibernate.DefaultHibernateUser</scheme-name>
    <scheme-ref>default</scheme-ref>
    <high-units>10000</high-units>
    <expiry-delay>7200</expiry-delay>
    </local-scheme>
It's possible to define a local-scheme mapping for a cache key without defining certain parameters (e.g. `<high-units>` ). In such a cases, their parameters will be inherited from `scheme-ref` scheme, which is the `default` scheme in our case. ## Important Caches
| The following suggestions are general guidelines. In cases of large databases, 20-30% of the size of the table may be unnecessarily large. Check the effectiveness and Percent Used categories in the cache for more specific assessments.
`com.atlassian.confluence.core.ContentEntityObject` (known as `Content Objects` cache) should be set to at least 20-30% of the number of content entity objects (pages, comments, emails, news items) in your system. To find the number of content entity objects, use the query `select count(*) from CONTENT where prevver is null`. `com.atlassian.confluence.core.ContentEntityObject.bodyContents` (known as `Content Body Mappings` cache) should be set to at least 20% of the number of content entity objects (pages, comments, emails, news items) in your system. To find the number of content entity objects, use the query `select count(*) from CONTENT where prevver is null`. `com.atlassian.confluence.security.PermissionCheckDispatcher.isPermitted()` (known as `User Authorized URLs` cache) should be set to at least the number of concurrent users you expect to access Confluence at the same time `com.atlassian.user.impl.hibernate.DefaultHibernateUser` (known as `Users` cache) should be set to the number of users you have: `select count (*) from users`. Note that by default, this will also control the LDAP user's cache, including expiration. `com.atlassian.confluence.security.SpacePermission` (known as `Permissions` cache) should be set to the number of space permissions in your deployment (a good rule of thumb is 20 times the number of spaces). You can find the number of space permissions using the query `select count(*) from SPACEPERMISSIONS`. ## Cache Tuning Follow-Up After you have made changes to your cache config, doing a follow up on the changes in the next week or after the expected performance spike would be important. Make sure that you take a screenshot of the cache statistics before and after the change. Then compare them with the cache statistics in the later period where performance improvement is expected.
| You can monitor what's in the cache by using a JSP included in the Confluence distribution. Browse to <base-URL>/admin/cachecontents.jsp to monitor the cache contents.
##### RELATED TOPICS Cache Performance Tuning for Specific Problems Confluence Cache Schemes Performance Testing Scripts Working with Confluence Logs Operating Large or Mission-Critical Confluence Installations Confluence Clustering Overview Requesting Performance Support Administrators Guide Configuration Guide Attachments: size.png (image/png) size.png (image/png) cacheKey.png (image/png)

Document generated by Confluence on Nov 05, 2009 23:27