Confluence Docs 2.10 : Cache Performance Tuning
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
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:
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 fileThe 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 MappingsThe 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 fileThe 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 fileIf 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 nameIf 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
Cache Tuning Follow-UpAfter 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 TOPICSCache Performance Tuning for Specific Problems |
![]() |
Document generated by Confluence on Dec 03, 2008 15:04 |