Default HCL Cache configuration

The HCL Cache cache_cfg.yaml configuration file contains default cache configurations.

To make changes to any defaults that are set in this file, modify the respective properties within the custom cache_cfg-ext.yaml file. This HCL Cache configuration file can be used to update defaults or set new configurations for custom caches. The cache_cfg-ext.yaml file is contained in the configuration maps in Kubernetes. Settings in the custom configuration file, which shares the same format as the default configuration file, override settings in the default configuration file.

For more information about the caching defaults stored in Kubernetes, see the sample Configuration.md file stored in the HCL Commerce Github repository.

Configuration Description
clientId This value is used to identify the originating container. The clientId is stored along with cache entries and used with invalidation messages.

On a Kubernetes environment, ${HOSTNAME} maps to the POD name. The {UUID} string, if found, is replaced by a generated universally unique identifier. This can be used in scenarios where multiple servers share the same hostname (For example, localhost).

namespace An optional namespace. If configured, the namespace is pre-appended to all the cache names in the Redis server. This is done to allow multiple environments to share the same Redis database.

This parameter is configured by default to match the tenant, environment and environment type.
logMetricsFrequency The frequency in seconds at which cache metrics are written to the logs. The default value is 900 (15 minutes).
The logger can be disabled by:
  • setting the logMetricsFrequency to 0;
  • Or by setting the logger to off
    com.hcl.commerce.cache.MetricsLogger=off​
redis
enabled Whether Redis is enabled.

By default this value is set to false.

Use the value true in the custom HCL Cache configuration file to enable remote caching.
yamlConfig

Path to the YAML configuration file for the Redis connection.

By default this value is set to /SETUP/hcl-cache/redis_cfg.yaml.
circuitBreaker

For caches that enable both local and remote interfaces, the circuit breaker configuration allows the cache to work independently in local mode during a Redis outage.

A cache is set in outage mode when conditions for both minimumFailureTimeMs and minimumConsecutiveFailures are met. During this time, connections to Redis are retried only after the time interval that is set by retryWaitTimeMs has elapsed.

When retryWaitTimeMs is reached, the circuit breaker allows connection attempts to the Redis server to resume. A successful request restores the connection from outage mode.

If the number of failures continues, and reaches the value set in minimumConsecutiveFailuresResumeOutage, the client is once again set in outage mode, and must again reach the retryWaitTimeMs value before the re-establishment of a connection is attempted.

The minimumConsecutiveFailuresResumeOutage setting is used to allow for quick testing of the connection after an outage without having to wait for minimumFailureTimeMs and minimumConsecutiveFailures values to be reached again.

See also maxTimeToLiveWithRemoteOutage.
circuitBreaker configurations retryWaitTimeMs Once a cache is set in outage mode, retryWaitTimeMs is the time, in milliseconds, that must elapse before the Redis connection is retried.

By default this value is set to 30000 (30 seconds).
minimumFailureTimeMs The time, in milliseconds, that must elapse before a cache can be put into outage mode. This amount of time, and minimumConsecutiveFailures must be satisfied before the circuit breaker closes the Redis connection.

By default this value is set to 10000 (10 seconds).
minimumConsecutiveFailures

The minimum number of consecutive connection attempt failures before a cache can be set in outage mode.

This value, and minimumFailureTimeMs must be satisfied before the circuit breaker closes the Redis connection.

By default this value is set to 20 connection attempts.
minimumConsecutiveFailuresResumeOutage

The minimum number of consecutive connection attempt failures before a cache can be set back into outage mode.

When a connection is in outage mode and reaches the retryWaitTimeMs value, the circuit breaker will allow connection attempts to the Redis server.

In order to allow for quick testing of the connection without an undue excess of connection attempts, the minimumConsecutiveFailuresResumeOutage is used.

If minimumConsecutiveFailuresResumeOutage is reached, the connection is placed back into outage mode, without having to wait for the entire minimumFailureTimeMs and minimumConsecutiveFailures condition cycle to be satisfied once again.

By default this value is set to 2 connection attempts.
cacheConfigs
cacheName The name of the cache to configure. The size and size in megabytes parameters are obtained from the DynaCache configuration in WebSphere Application Server. The cache name defaultCacheConfig is reserved and specifies the defaults for all caches.
localCache
localCache configurations enabled Enables this cache to make use of local caching.
maxInactivityWithRemote The time, in seconds, this cache can remain inactive in its local state.

When remote caching is enabled, this setting enforces a maximum inactivity time allowed for this cache before being invalidated. This optional configuration is used to have shorter timeouts when the local cache is acting as a replica/near cache of the remote cache.

By default this value is set to 0 (disabled).
maxTimeToLiveWithRemote The time, in seconds, that this cache can remain valid.

When remote caching is enabled, this setting enforces a maximum timeout allowed for this cache.

This optional configuration can be used to specify shorter timeouts when the local cache is acting as a near cache for the remote cache.

By default this value is set to 0 (disabled).
maxTimeToLiveWithRemoteOutage The time, in seconds, this cache can remain valid during a remote outage.

When the circuit breaker is enabled, and a cache is in outage mode, this setting is used to enforce a new timeout on the local cache.

A short timeout is used as invalidations are not available if Redis is not operational.

By default this value is set to 300 seconds.
remoteCache
remoteCache configurations enabled Enables this cache to rely on the use of remote caching.

By default this is set to enabled when a Redis connection is configured.
defaultTimeout Normally cache entries specify a maximum time to live (timeout) in seconds when they are created. But if no timeout is specified by the cache entry, then the defaultTimeout setting is used for that cache entry.

By default, the defaultTimeout parameter value is set to 172800 seconds (2 days).

Important: Redis must be configured with a volatile-* less-recently-used (LRU) setting. For more information, see Using Redis as an LRU cache in the Redis documentation.
maximumTimeout Normally cache entries specify a maximum time to live (timeout) in seconds when they are created. But if no timeout is specified by the cache entry, then the defaultTimeout setting is used for that cache entry.

If the defaultTimeout is set to a value that is higher than the maximumTimeout, then the maximumTimeout value is used.

By default, the maximumTimeout parameter value is set to 604800 seconds (7 days).
HCL Commerce Version 9.1.10.0 or laterCodec options (compression) The codec configuration element under remoteCache can be used to modify the default binary codec that Redis uses to serialise cache entry values. The HCL Cache will utilise the LZ4 compression method for compressing.
cacheName:
  remoteCache:
    enabled: true
    codec: binary
Compression is ideal for caches with huge cache entries (such as baseCache), which might take up several GC of Redis server space. Although compression reduces the amount of stored values and network traffic, it comes at the cost of compressing and expanding entries. This is done in the server, which might cause delays and increase CPU use.
HCL Commerce Version 9.1.10.0 or laterCache Directives The cache name element may be used to activate cache directives. They are only enabled for baseCache by default.
baseCache:
  enableDirectives: true

Although the HCL Cache allows for local and/or remote caching at the cache level, it is sometimes preferable to select which caches are used at the cache entry level.

Cache entries for search operations may grow unbounded and have limited reusability (hit ratios). While local level caching can be beneficial, distant caching can be costly since it adds I/O overhead, consumes a large amount of Redis memory, and necessitates frequent Redis memory maintenance operations.

When a cache's directives are enabled, the cachespec.xml can contain the following attributes to govern whether local or remote caching is utilised at the cache entry level:

DC_HclCacheSkipRemote:
Special attribute that instructs the HCL Cache not to use remote cache for this entry even when enabled for the cache.
DC_HclCacheSkipLocal:
Special attribute that instructs the HCL Cache not to use local cache for this entry even when enabled for the cache.

<component id="DC_HclCacheSkipRemote" type="attribute">
  <required>true</required>
</component>