Global configuration of the cache-chroniclemap libModule is done in the gerrit.config file in the site's etc directory.
Information about gerrit caches mechanism can be found in the relevant documentation section.
Chronicle-map supports most of the cache configuration parameters, such as:
maxAge: Maximum age to keep an entry in the cache. Gerrit docs
refreshAfterWrite: Duration after which we asynchronously refresh the cached value. Gerrit docs
diskLimit: Total size in bytes of the keys and values stored on disk. Defaults are per-cache and can be found in the relevant documentation: Gerrit docs
NOTE: a per gerrit documentation, a positive value is required to enable disk storage for the cache. However, the provided value cannot be used to limit the size of the file, since that is the result of chronicle-map pre-allocation and it is a function of the number of entries, average sizes and bloat factor, rather than the number of values stored in it.
Chronicle-map implementation however might require some additional configuration
cache.<name>.avgKeySize : The average number of bytes to be allocated for the key of this cache. If key is a boxed primitive type, a value interface or Byteable subclass, i. e. if key size is known statically, it is automatically accounted by chronicle-map. In this case, this value will be ignored.
cache.<name>.avgValueSize : The average number of bytes to be allocated for a value of this cache. If key is a boxed primitive type, a value interface or Byteable subclass, i. e. if key size is known statically, it is automatically accounted by chronicle-map. In this case, this value will be ignored.
cache.<name>.maxEntries : The number of entries that this cache is going to hold, at most. The actual number of entries needs to be less or equal to this value.
cache.<name>.maxBloatFactor : the maximum number of times this cache is allowed to grow in size beyond the configured target number of entries.
Set this value to the theoretical maximum of stored entries, divided by the configured entries.
Chronicle Map will allocate memory until the actual number of entries inserted divided by the number configured through maxEntries is not higher than the configured maxBloatFactor.
Chronicle Map works progressively slower when the actual size grows far beyond the configured size, so the maximum possible maxBloatFactor() is artificially limited to 1000. Default: 1
cache.<name>.percentageFreeSpaceEvictionThreshold : The percentage of free space in the last available expansion of chronicle-map beyond which cold cache entries will start being evicted.Since the eviction routine is scheduled as background task every 30 seconds, this value should always be < 100. This is to allow for additional entries to be inserted into the cache between the execution of two eviction runs.
How much that margin is, depends on how fast the cache can increase between two eviction runs: caches that populate more quickly might need a lower value, and vice-versa.
Default: 90
Unless overridden by configuration, sensible default values are be provided for standard caches.
Please note that even though defaults allow an out-of-the-box usage of the chronicle-map cache, they are not necessarily suitable for a production environment.
A deep understanding of your Gerrit data is crucial to tune each cache accordingly. Please refer to the configuration to understand how to choose sensible values.
These defaults have been retrieved by observing actual key and value sizes as explained in the official documentation
They are based on the assumption that your Gerrit instance will not have more than 1000 accounts overall, logged-in at the same time and no more than 1000 medium sized changes.
Information on which values each cache is actually initialized with, can be found in the error_log at startup, in particular two values are also logged to help gather important statistics about the current file cache status:
remainingAutoResizes : the number of times in the future the cache can automatically expand its capacity. The limit to the number of times the map can expand is set via the maxBloatFactor. if remainingAutoResizes drops to zero,this cache is no longer able to expand and it will not be able to take more entries, failing with a IllegalStateException official documentation
percentageFreeSpace : the amount of free space in the cache as a percentage. When the free space gets low ( around 5% ) the cache will automatically expand (see remainingAutoResizes). If the cache expands you will see an increase in the available free space. official documentation
percentageHotKeys : The percentage of hot keys that can be kept in-memory. When performing evictions, hot keys will be preserved and only cold keys will be evicted from chronicle-map, in random order.
This value implies a trade-off between eviction speed and eviction accuracy.
The smaller the number of hotKeys allocated, the quicker the eviction phase will be. However, this will increase the chance of evicting entries that were recently accessed.
Conversely, the higher the number of hotKeys allocated, the higher will be the accuracy in evicting only recently accessed keys, at the price of a longer time spent doing evictions.
In order to ensure there is always a cold entry to be evicted, the number of percentageHotKeys always needs to be less than maxEntries.
Constraints: [1-99] Default: 50
These are the provided default values:
web_sessions:avgKeySize: 45 bytesavgValueSize: 221 bytesmaxEntries: 1000maxBloatFactor: 1Allows up to 1000 users to be logged in.
change_notes:avgKeySize: 36 bytesavgValueSize: 10240 bytesmaxEntries: 1000maxBloatFactor: 2Allow for a dozen review activities (votes, comments of medium length) to up to 1000 operations. maxBloatFactor allows to go twice over this threshold.
accounts:avgKeySize: 30 bytesavgValueSize: 256 bytesmaxEntries: 1000maxBloatFactor: 1Allows to cache up to 1000 details of active users, including their display name, preferences, mail, etc.
diff:avgKeySize: 98 bytesavgValueSize: 10240 bytesmaxEntries: 1000maxBloatFactor: 3Allow for up to 1000 medium sized diffs between two commits to be cached. maxBloatFactor allows to go three times over this threshold.
diff_intraline:avgKeySize: 512 bytesavgValueSize: 2048 bytesmaxEntries: 1000maxBloatFactor: 2Allow for up to 1000 medium sized diffs between two files to be cached. maxBloatFactor allows to go twice over this threshold.
external_ids_map:avgKeySize: 24 bytesavgValueSize: 204800 bytesmaxEntries: 2maxBloatFactor: 1This cache holds a map of the parsed representation of all current external IDs. It may temporarily contain 2 entries, but the second one is promptly expired. This defaults allow to contain up to 1000 entries per map, roughly.
oauth_tokens:avgKeySize: 8 bytesavgValueSize: 2048 bytesmaxEntries: 1000maxBloatFactor: 1caches information about the operation performed by a change relative to its parent. Allow to cache up to 1000 entries.
mergeability:avgKeySize: 79 bytesavgValueSize: 16 bytesmaxEntries: 65000maxBloatFactor: 2Caches information about the mergeability status of up to 1000 open changes.
pure_revert:avgKeySize: 55 bytesavgValueSize: 16 bytesmaxEntries: 1000maxBloatFactor: 1Caches the result of checking if one change or commit is a pure/clean revert of another, for up to 1000 entries.
persisted_projects:avgKeySize: 128 bytesavgValueSize: 1024 bytesmaxEntries: 250maxBloatFactor: 2Caches the project description records from the refs/meta/config branch of each project. Allow up to 250 projects to be cached. maxBloatFactor allows to go twice over this threshold.
conflicts:avgKeySize: 70 bytesavgValueSize: 16 bytesmaxEntries: 1000maxBloatFactor: 1Caches whether two commits are in conflict with each other. Allows to hold up to 1000 conflicting changes.
GENERAL DEFAULTS:Caches that do not provide specific configuration in the [cache "<name>"] stanza and are not listed above, will fallback to use generic defaults:
avgKeySize: 128 bytesavgValueSize: 2048 bytesmaxEntries: 1000maxBloatFactor: 1When reading the persisted cache file, chronicle-map assumes the configuration that was used to create the file for the first time. This means, that changing the configuration is not going to update entries, average key size and average value size as your needs grow.
If you need more entries, or different key values, you'll need to generate a brand new persistent cache (i.e. delete the old one).
More information on recovery can be found in the Official documentation
This module provides tooling to help understand how configuration should be optimized for chronicle-map. More information in the tuning documentation.