Azure-Redis-Lettuce-Best-Practices.md

• Azure Redis Lettuce Best Practices
  • Async vs Sync vs React
  • When to use connection pool
  • Cluster
  • Master/Slave
  • Important client options to consider
  • Pipelining
  • Log Pool Usage Periodically
  • Choose PoolConfig settings with care
  • Important Cluster specific options to consider

Azure Redis Lettuce Best Practices

Async vs Sync vs React

• If your project already used React pattern, go for React API without doubt. Read more here https://github.com/lettuce-io/lettuce-core/wiki/Reactive-API-%284.
• If you don't know which one to use, go for Async API since both async and sync are implemented asyncly. Lettuce facilitates asynchronicity from building the client on top of netty that is a multithreaded, event-driven I/O framework. All communication is handled asynchronously. Read more here https://github.com/lettuce-io/lettuce-core/wiki/Asynchronous-API
• If you need to block on some commands execution, synchronously block on RedisFuture<T>

When to use connection pool

• Connection pool is only needed when you need many dedicated connections such as transactions or blocking operation with each worker thread get its dedicated connection
• Use many connections doesn't necessarily improve the performance and concurrency since Redis is single threaded and every reqeust is handled serially.
• The StatefulRedisConnection object is thread-safe and can be used from multiple threads at the same time.
• This pool should be configured once and reused.
• Make sure to return the StatefulRedisConnection back to the pool when done, otherwise you will leak it. Recommend to use try-with-resource, which return it automatically.
• Read more here https://github.com/lettuce-io/lettuce-core/wiki/Connection-Pooling
• Sample code here

Cluster

• When you enabled cluster mode in Azure redis, you should use cluster API. Read more here https://github.com/lettuce-io/lettuce-core/wiki/Redis-Cluster
• One known issue you should be aware redis/lettuce#712. This issue has been fixed in 4.5.0-SNAPSHOT.
• Sample code here

Master/Slave

• When you use Azure Redis Standard or Premium, you could use Master/Salve API or normal API. Read more here https://github.com/lettuce-io/lettuce-core/wiki/Master-Slave
• Only worked after 4.4.3.Final if you use Master/Salve API and SSL.
• Sample code here

Important client options to consider

Setting	Description
socketOptions.connectTimeout	How long to allow for new connections to be established (in milliseconds). In general, this should be at least 5000ms. If your client application tends to have high spikes CPU usage, setting this to 15000ms or 20000ms would be a good idea.
port	In Azure, 6379 is non-ssl and 6380 is SSL/TLS. Important Note: 6379 is disabled by default - you have to explicitly enable this insecure port if you wish to use it.

More details here https://github.com/lettuce-io/lettuce-core/wiki/Client-Options

Pipelining

• This will improve the throughput of the application. Read more about redis pipelining here https://redis.io/topics/pipelining.
• Lettuce do pipelining automatically for you. Read more here https://github.com/lettuce-io/lettuce-core/wiki/Pipelining-and-command-flushing

Log Pool Usage Periodically

• Debugging performance problems due to pool contention issues will be easier if you log the pool usage regularly.
• If you ever get an error when trying to get a connection from the pool, you should definitely log usage stats.
• Sample code here

Choose PoolConfig settings with care

Setting	Description
maxTotal	This setting controls the max number of connections that can be created at a given time. Note that each connection does have some memory and CPU overhead, so setting this to a very high value may have negative side effects. If not set, the default value is 8, which is probably too low for most applications. When chosing a value, consider how many concurrent calls into Redis you think you will have under load.
maxIdle	This is the max number of connections that can be idle in the pool without being immediately evicted (closed). If not set, the default value is 8. I would recommend that this setting be configured the same as maxTotal to help avoid connection ramp-up costs when your application has many bursts of load in a short period of time. If a connection is idle for a long time, it will still be evicted until the idle connection count hits minIdle (described below).
minIdle	This is the number of "warm" connections (e.g. ready for immediate use) that remain in the pool even when load has reduced. If not set, the default is 0. When choosing a value, consider your steady-state concurrent requests to Redis. For instance, if your application is calling into Redis from 10 threads simultaneously, then you should set this to at least 10 (probably a bit higher to give you some room.
blockWhenExhausted	This controls behavior when a thread asks for a connection, but there aren't any that are free and the pool can't create more (due to maxTotal). If set to true, the calling thread will block for maxWaitMillis before throwing an exception. The default is true and I recommend true for production environments. You could set it to false in testing environments to help you more easily discover what value to use for maxTotal.
maxWaitMillis	How long to wait in milliseconds if calling Pool.getResource() will block. The default is -1, which means block indefinitely. I would set this to the same as the socketTimeout configured. Related to blockWhenExhausted.
TestOnBorrow	Controls whether or not the connection is tested before it is returned from the pool. The default is false. Setting to true may increase resilience to connection blips but may also have a performance cost when taking connections from the pool. In my quick testing, I saw a noticable increase in the 50th percentile latencies, but no significant increase in 98th percentile latencies.

• Sample code here

Important Cluster specific options to consider

Setting	Description
enablePeriodicRefresh	Periodically refresh nodes topology
enableAllAdaptiveRefreshTriggers	Recommend to enable this. This will trigger nodes topology refresh when encounter MOVED, ASKED or PESISTENT_RECONNECT (which means refreshTriggersReconnectAttempts for a specific node has been reached). This would take effect when Azure redis do the patching or other kinds of failover.

• Sample code here

• More details here https://github.com/lettuce-io/lettuce-core/wiki/Client-Options

The sample code for pool usage gives 404. Could you please add the sample code?

@lawruban https://github.com/Azure-Samples/azure-cache-redis-samples/tree/main/samples/java/ClientSamples/src/main/java/lettuce This should suffice. Seems wrong is attached above.