キャッシュ パフォーマンスのチューニング

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.

キャッシュ サイズが大きくなるほど、実行時に必要なメモリが多くなるため、Confluence の Java プロセスへのメモリの割り当てと、サーバー上で使用可能な物理メモリを見直す必要があります。

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.

キャッシュのチューニング例

Confluence のキャッシュをチューニングする具体例として、次の表を見てみましょう。

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
• 有効率が低い

「有効率」と「使用率」の対応関係を確認します。使用率が低いキャッシュのサイズを下げる必要はありません。キャッシュがいっぱいになるまでメモリの消費は増えません。

上の条件をもとにすると、"添付ファイル"、"データベース クエリ"、"ユーザー" のキャッシュは、サイズを拡大して、有効率を改善する必要があります。

保存された情報が古くなったり、使用されなかったりすると、情報は期限切れとなり、キャッシュから除去されます。キャッシュの有効期間は使用回数や使用頻度をもとにしています。

設定ファイルの保管場所

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 Problem

If you are using Confluence earlier than version 2.9 you might find your 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.

関連トピック

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