[PaaS only]{class="badge informative" title="Applies to Adobe Commerce on Cloud projects (Adobe-managed PaaS infrastructure) and on-premises projects only."}

Best practices for Redis service configuration

Configure Redis L2 cache

Configure the Redis L2 cache by setting the REDIS_BACKEND deployment variable in the .magento.env.yaml configuration file.

stage:
  deploy:
    REDIS_BACKEND: '\Magento\Framework\Cache\Backend\RemoteSynchronizedCache'

For environment configuration on Cloud infrastructure, see the REDIS_BACKEND in the Commerce on Cloud Infrastructure Guide.

For on-premises installations, see Configure Redis page caching in the Configuration Guide.

L2 cache memory sizing (Adobe Commerce Cloud)

L2 cache uses a temporary file system as a storage mechanism. Compared with specialized key-value database systems, a temporary file system doesn’t have a key eviction policy to control memory usage.

The lack of memory usage control can cause the L2 cache memory usage to grow over time by accumulating the stale cache.

To avoid memory exhaustion of L2 cache implementations, Adobe Commerce clears the storage when a certain threshold is reached. The default threshold value is 95%.

It is important to adjust the L2 cache memory maximum usage based on project requirements for cache storage. Use one of the following methods to configure memory cache sizing:

The following code shows an example configuration in the .magento.env.yaml file:

stage:
  deploy:
    REDIS_BACKEND: '\Magento\Framework\Cache\Backend\RemoteSynchronizedCache'
    CACHE_CONFIGURATION:
      _merge: true
      frontend:
        default:
          backend_options:
            cleanup_percentage: 90

Cache requirements can vary based on project configuration and custom third-party code. The scope of the L2 cache memory sizing allows the L2 cache to operate without too many threshold hits.
Ideally, L2 cache memory usage should stabilize at a certain level below the threshold, just to avoid frequent storage clearing.

You can check L2 cache storage memory usage on each node of the cluster using the following CLI command and looking for the /dev/shm line.
The usage could vary across different nodes, but it should converge to the same value.

df -h

Enable Redis slave connection

Enable a Redis slave connection in the .magento.env.yaml configuration file to allow only one node to handle read-write traffic while the other nodes handle the read-only traffic.

stage:
  deploy:
    REDIS_USE_SLAVE_CONNECTION: true

See REDIS_USE_SLAVE_CONNECTION in the Commerce on Cloud Infrastructure Guide.

For Adobe Commerce on-premises installations, configure the new Redis cache implementation using the bin/magento:setup commands. See Use Redis for default cache in the Configuration Guide.

Pre-load keys

To reuse data between pages, list the keys for preload in the .magento.env.yaml configuration file.

stage:
  deploy:
    REDIS_BACKEND: '\Magento\Framework\Cache\Backend\RemoteSynchronizedCache'
    CACHE_CONFIGURATION:
      _merge: true
      frontend:
        default:
          id_prefix: '061_'                       # Prefix for keys to be preloaded
          backend_options:
            preload_keys:                         # List the keys to be preloaded
              - '061_EAV_ENTITY_TYPES:hash'
              - '061_GLOBAL_PLUGIN_LIST:hash'
              - '061_DB_IS_UP_TO_DATE:hash'
              - '061_SYSTEM_DEFAULT:hash'

For on-premises installations, see Redis preload feature in the Configuration Guide.

Enable stale cache

Reduce lock waiting times and enhance performance—especially when dealing with numerous Blocks and Cache keys—by using an outdated cache while generating a new cache in parallel. Enable stale cache and define cache types in the config.php configuration file (cloud only):

'cache' => [
        'frontend' => [
            'stale_cache_enabled' => [
                'backend' => '\\Magento\\Framework\\Cache\\Backend\\RemoteSynchronizedCache',
                'backend_options' => [
                    'remote_backend' => '\\Magento\\Framework\\Cache\\Backend\\Redis',
                    'remote_backend_options' => [
                        'persistent' => 0,
                        'server' => 'localhost',
                        'database' => '4',
                        'port' => '6370',
                        'password' => ''
                    ],
                    'local_backend' => 'Cm_Cache_Backend_File',
                    'local_backend_options' => [
                        'cache_dir' => '/dev/shm/'
                    ],
                    'use_stale_cache' => true,
                ],
                'frontend_options' => [
                    'write_control' => false,
                ],
            ]
        ],
        'type' => [
            'default' => ['frontend' => 'default'],
            'layout' => ['frontend' => 'stale_cache_enabled'],
            'block_html' => ['frontend' => 'stale_cache_enabled'],
            'reflection' => ['frontend' => 'stale_cache_enabled'],
            'config_integration' => ['frontend' => 'stale_cache_enabled'],
            'config_integration_api' => ['frontend' => 'stale_cache_enabled'],
            'full_page' => ['frontend' => 'stale_cache_enabled'],
            'translate' => ['frontend' => 'stale_cache_enabled']
        ],
    ]

For configuring on-premises installations, see Stale cache options in the Configuration Guide.

Separate Redis cache and session instances

Separating the Redis cache from Redis session allows you to manage the cache and sessions independently. It prevents cache issues from affecting sessions, which could impact revenue. Each Redis instance runs on its own core, which improves performance.

During deployment, you should see the following lines in the build and deploy log:

W:   - Downloading colinmollenhour/credis (1.11.1)
W:   - Downloading colinmollenhour/php-redis-session-abstract (v1.4.5)
...
W:   - Installing colinmollenhour/credis (1.11.1): Extracting archive
W:   - Installing colinmollenhour/php-redis-session-abstract (v1.4.5): Extracting archive
...
[2022-08-17 01:13:40] INFO: Version of service 'redis' is 6.0
[2022-08-17 01:13:40] INFO: Version of service 'redis-session' is 6.0
[2022-08-17 01:13:40] INFO: redis-session will be used for session if it was not override by SESSION_CONFIGURATION

Cache compression

If you are using over 6GB of Redis maxmemory, you can use cache compression to reduce the space consumed by the keys. Be aware that there is a trade-off with client-side performance. If you have spare CPUs, enable it. See Use Redis for session storage in the Configuration Guide.

stage:
  deploy:
    REDIS_BACKEND: '\Magento\Framework\Cache\Backend\RemoteSynchronizedCache'
    CACHE_CONFIGURATION:
      _merge: true;
      frontend:
        default:
          backend_options:
            compress_data: 4              # 0-9
            compress_tags: 4              # 0-9
            compress_threshold: 20480     # don't compress files smaller than this value
            compression_lib: 'gzip'       # snappy and lzf for performance, gzip for high compression (~69%)

Enable Redis asynchronous freeing (lazyfree)

To enable lazyfree on Adobe Commerce on cloud infrastructure, submit an Adobe Commerce Support ticket requesting the following Redis configuration be applied to your environment(s):

lazyfree-lazy-eviction yes
lazyfree-lazy-expire yes
lazyfree-lazy-server-del yes
replica-lazy-flush yes
lazyfree-lazy-user-del yes

When lazyfree is enabled, Redis offloads memory reclamation to background threads for evictions, expirations, server-initiated deletes, user deletes, and replica dataset flushes. This reduces main-thread blocking and can lower request latency.

Enable Redis multithreaded I/O

To enable Redis I/O threading on Adobe Commerce on cloud infrastructure, submit an Adobe Commerce Support ticket requesting the configuration below. This can improve throughput by offloading socket reads/writes and command parsing from the main thread, at the cost of higher CPU usage. Validate under load and monitor your hosts.

io-threads-do-reads yes
io-threads 8 # choose a value lower than the number of CPU cores (check with nproc), then tune under load

Increase Redis client timeouts and retries

Raise the cache client’s tolerance to transient saturation by adjusting the backend options in .magento.env.yaml:

stage:
  deploy:
    CACHE_CONFIGURATION:
      _merge: true
      frontend:
        default:
          backend_options:
            read_timeout: 10
            connect_retries: 5

These settings increase client tolerance to brief congestion on Redis by extending the reply wait window and retrying connection setup. This can reduce intermittent cannot connect to localhost:6370 and read-timeout errors during short spikes.

Additional information