This page last changed on Nov 05, 2008 by rhartono.

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:

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

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/classes/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:


Depending on what objects are stored in the cache, when you increase the size of a cache Confluence will require more memory for that. For example a "Space Permissions" cache (com.atlassian.confluence.security.CachingSpacePermissionManager.permissions) of size 10k consumes approximately 8MB of memory.

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.

Your new cache scheme must be defined within the <caching-schemes>...</caching-schemes> tags.

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.

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


size.png (image/png)
size.png (image/png)
Document generated by Confluence on Dec 03, 2008 15:04