Cache Performance Tuning

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 sizes to suit its environment.

Note that larger cache sizes will require more memory at runtime, so you should review the memory allocation of the Confluence Java process and the physical memory available on your server.

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.

Cache tuning example

As an example of how to tune Confluence's caches, let's have a look at the following table:

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
• 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 confluence-coherence-cache-config.xml (or confluence-coherence-cache-config-clustered.xml for clustered instance) which is stored in confluence/WEB-INF/lib/confluence-x.x.x.jar (x.x.x is the Confluence version number). Extracting and placing the XML file in /WEB-INF/classes/ will override the configuration file in the JAR file.

Cache Key Mappings

The cache configuration file configures caches by their keys. You can find the mapping of cache keys to the friendly cache names displayed on the administration page inside ConfluenceActionSupport.properties file, found in the confluence/WEB-INF/confluence-x.x.x.jar file, in /com/atlassian/confluence/core/. Search for "Friendly cache names" in this file to find the list.

Using our example from the table above, if we were to increase the Users cache we would need to find its cache key mapping in ConfluenceActionSupport.properties.

...
cache.name.com.atlassian.user.impl.hibernate.DefaultHibernateExternalEntity=Users (External Mappings)
cache.name.com.atlassian.user.impl.hibernate.DefaultHibernateExternalEntity.groups=Users (External Groups)
cache.name.com.atlassian.user.impl.hibernate.DefaultHibernateGroup=Groups
cache.name.com.atlassian.user.impl.hibernate.DefaultHibernateGroup.externalMembers=Groups (External Members)
cache.name.com.atlassian.user.impl.hibernate.DefaultHibernateGroup.localMembers=Groups (Local Members)
cache.name.com.atlassian.user.impl.hibernate.DefaultHibernateUser=Users
...

The correct cache key mappings for Users cache would be cache.name.com.atlassian.user.impl.hibernate.DefaultHibernateUser. Do not get confused with Users (External Mappings) and Users (External Groups) which are two separate caches themselves. "Users" is the friendly name for cache.name.com.atlassian.user.impl.hibernate.DefaultHibernateUser.

At the moment cache tuning has to be done manually by editing the Coherence Configuration File, there is a feature request to do cache tweaking in the administration console: CONF-12836. Please have a look at a related feature request to automate cache tweaking recommendation in Confluence: CONF-12837

Understanding the Coherence configuration file

The Coherence configuration file is a mapping of cache keys to cache schemes. Each cache scheme controls the expiry 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 which is 1000.

In our example, cache.name.com.atlassian.user.impl.hibernate.DefaultHibernateUser is not explicitly defined in the caching scheme mappings. Hence to increase the size, 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>large</scheme-name>
</cache-mapping>

"large" is one of the common schemes defined in confluence-coherence-cache-config.xml which is set to 10000. If you like, you can define the scheme name to something smaller such as "medium" which is set to 5000.

A successful edit will increase the Size of the "Users" cache to 10000:

Defining a scheme name

If you find that none of the cache schemes is sufficient for your use, you can always define a new scheme.

The following is an example of a new cache scheme:

<local-scheme>
  <scheme-name>extraLarge</scheme-name>
  <scheme-ref>default</scheme-ref>
  <high-units>20000</high-units>
</local-scheme>

It's possible to define a local-scheme mapping for a cache key without defining the <high-units> tags. In such a case, their sizes will be set to the default value which is 1000. If you were to increase the size of such caches, you need to search for their "local-scheme" definition and add the desired "high-units" values.

Using the "Content Bodies" cache in our example, which mapped to "com.atlassian.confluence.core.BodyContent". The cache size has been increased from 1000 (it wasn't defined previously) to 5000 in the following example:

<local-scheme>
  <scheme-name>cache:com.atlassian.confluence.core.BodyContent</scheme-name>
  <scheme-ref>default</scheme-ref>
  <high-units>5000</high-units>
  <expiry-delay>0s</expiry-delay>
</local-scheme>

Important Caches

• 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
• 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 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.

Known Problems for LDAP Caches

• If you are using Confluence earlier than version 2.9 you might find your LDAP cache size change does not show up in Confluence. This is a known issue that has a work around, please follow the bug report in CONF-11857.
• If you have changed the name of your LDAP key from ldapRepository, you will have to change the name in your cache name. This is described in CONFKB181536872.

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