Production usage

Get your Lettuce app ready for production

This guide offers recommendations to get the best reliability and performance in your production environment.

Checklist

Each item in the checklist below links to the section for a recommendation. Use the checklist icons to record your progress in implementing the recommendations.

- [ ] [Timeouts](#timeouts)
- [ ] [Cluster topology refresh](#cluster-topology-refresh)
- [ ] [Warm up cluster connections](#warm-up-cluster-connections)
- [ ] [DNS cache and Redis](#dns-cache-and-redis)
- [ ] [Exception handling](#exception-handling)
- [ ] [Connection and execution reliability](#connection-and-execution-reliability)
- [ ] [Smart client handoffs](#seamless-client-experience)

Recommendations

The sections below offer recommendations for your production environment. Some of them may not apply to your particular use case.

Timeouts

Lettuce provides timeouts for many operations, such as command execution, SSL handshake, and Sentinel discovery. By default, Lettuce uses a global timeout value of 60 seconds for these operations, but you can override the global timeout value with individual timeout values for each operation.

Tip:
Choosing suitable timeout values is crucial for your application's performance and stability and is specific to each environment. Configuring timeouts is only necessary if you have issues with the default values. In some cases, the defaults are based on environment-specific settings (e.g., operating system settings), while in other cases, they are built into the Lettuce driver. For more details on setting specific timeouts, see the Lettuce reference guide.

Prerequisites

To set TCP-level timeouts, you need to ensure you have one of Netty Native Transports installed. The most common one is netty-transport-native-epoll, which is used for Linux systems. You can add it to your project by including the following dependency in your pom.xml file:

<dependency>
    <groupId>io.netty</groupId>
    <artifactId>netty-transport-native-epoll</artifactId>
    <version>${netty.version}</version> <!-- e.g., 4.1.118.Final -->
    <classifier>linux-x86_64</classifier>
</dependency>

Once you have the native transport dependency, you can verify that by using the following code:

logger.info("Lettuce epool is available: {}", EpollProvider.isAvailable());

If the snippet above returns false, you need to enable debugging logging for io.lettuce.core and io.netty to see why the native transport is not available.

For more information on using Netty Native Transport, see the Lettuce reference guide.

Setting timeouts

Below is an example of setting socket-level timeouts. The TCP_USER_TIMEOUT setting is useful for scenarios where the server stops responding without acknowledging the last request, while the KEEPALIVE setting is good for detecting dead connections where there is no traffic between the client and the server.

RedisURI redisURI = RedisURI.Builder
        .redis("localhost")
        // set the global default from the default 60 seconds to 30 seconds
        .withTimeout(Duration.ofSeconds(30)) 
        .build();

try (RedisClient client = RedisClient.create(redisURI)) {
    // or set specific timeouts for things such as the TCP_USER_TIMEOUT and TCP_KEEPALIVE

    // A good general rule of thumb is to follow the rule
    // TCP_USER_TIMEOUT = TCP_KEEP_IDLE+TCP_KEEPINTVL * TCP_KEEPCNT
    // in this case, 20 = 5 + 5 * 3

    SocketOptions.TcpUserTimeoutOptions tcpUserTimeout = SocketOptions.TcpUserTimeoutOptions.builder()
            .tcpUserTimeout(Duration.ofSeconds(20))
            .enable().build();

    SocketOptions.KeepAliveOptions keepAliveOptions = SocketOptions.KeepAliveOptions.builder()
            .interval(Duration.ofSeconds(5))
            .idle(Duration.ofSeconds(5))
            .count(3).enable().build();

    SocketOptions socketOptions = SocketOptions.builder()
            .tcpUserTimeout(tcpUserTimeout)
            .keepAlive(keepAliveOptions)
            .build();

    client.setOptions(ClientOptions.builder()
            .socketOptions(socketOptions)
            .build());

    StatefulRedisConnection<String, String> connection = client.connect();
    System.out.println(connection.sync().ping());
}

Setting timeouts in Spring Data Redis

If you are using Spring Data Redis, you can set timeouts and keepalive settings using LettuceClientConfigurationBuilderCustomizer:

@Bean
public LettuceClientConfigurationBuilderCustomizer lettuceClientConfigurationBuilderCustomizer() {
    return clientConfigurationBuilder -> {
        // Configure TCP User Timeout
        // This is useful for scenarios where the server stops responding without
        // acknowledging the last request
        SocketOptions.TcpUserTimeoutOptions tcpUserTimeout = SocketOptions.TcpUserTimeoutOptions.builder()
                .tcpUserTimeout(Duration.ofSeconds(20))
                .enable()
                .build();

        // Configure TCP Keep-Alive
        // This is good for detecting dead connections where there is no traffic
        // between the client and the server
        SocketOptions.KeepAliveOptions keepAliveOptions = SocketOptions.KeepAliveOptions.builder()
                .interval(Duration.ofSeconds(5))  // TCP_KEEPINTVL: interval between probes
                .idle(Duration.ofSeconds(5))      // TCP_KEEPIDLE: time before first probe
                .count(3)                         // TCP_KEEPCNT: number of probes
                .enable()
                .build();

        // Build SocketOptions with both TCP User Timeout and Keep-Alive
        SocketOptions socketOptions = SocketOptions.builder()
                .tcpUserTimeout(tcpUserTimeout)
                .keepAlive(keepAliveOptions)
                .build();

        // Build ClientOptions with the configured SocketOptions
        ClientOptions clientOptions = ClientOptions.builder()
                .socketOptions(socketOptions)
                .build();

        // Apply the client options and command timeout to the builder
        clientConfigurationBuilder
                .clientOptions(clientOptions)
                .commandTimeout(Duration.ofSeconds(30));  // Global command timeout
    };
}

Cluster topology refresh

The Redis Cluster configuration is dynamic and can change at runtime. New nodes may be added, and the primary node for a specific slot can shift. Lettuce automatically handles MOVED and ASK redirects, but to enhance your application's resilience, you should enable adaptive topology refreshing:

RedisURI redisURI = RedisURI.Builder
        .redis("localhost")
        // set the global default from the default 60 seconds to 30 seconds
        .withTimeout(Duration.ofSeconds(30)) 
        .build();
        
// Create a RedisClusterClient with adaptive topology refresh
try (RedisClusterClient clusterClient = RedisClusterClient.create(redisURI)) {
    // Enable TCP keep-alive and TCP user timeout just like in the standalone example
    SocketOptions.TcpUserTimeoutOptions tcpUserTimeout = SocketOptions.TcpUserTimeoutOptions.builder()
            .tcpUserTimeout(Duration.ofSeconds(20))
            .enable()
            .build();

    SocketOptions.KeepAliveOptions keepAliveOptions = SocketOptions.KeepAliveOptions.builder()
            .interval(Duration.ofSeconds(5))
            .idle(Duration.ofSeconds(5))
            .count(3)
            .enable()
            .build();

    SocketOptions socketOptions = SocketOptions.builder()
            .tcpUserTimeout(tcpUserTimeout)
            .keepAlive(keepAliveOptions)
            .build();

    // Enable adaptive topology refresh
    // Configure adaptive topology refresh options
    ClusterTopologyRefreshOptions topologyRefreshOptions = ClusterTopologyRefreshOptions.builder()
            .enableAllAdaptiveRefreshTriggers()
            .adaptiveRefreshTriggersTimeout(Duration.ofSeconds(30))
            .build();
    
    ClusterClientOptions options = ClusterClientOptions.builder()
            .topologyRefreshOptions(topologyRefreshOptions)
            .socketOptions(socketOptions).build();

    clusterClient.setOptions(options);

    StatefulRedisClusterConnection<String, String> connection = clusterClient.connect();
    System.out.println(connection.sync().ping());
    connection.close();
}

Learn more about topology refresh configuration settings in the reference guide.

Warm up cluster connections

With a Redis Cluster, Lettuce opens connections to individual nodes lazily - the connection to a given shard is created the first time a command is routed to it. This keeps the connection footprint minimal, but it means the first requests after startup each pay the cost of establishing a new connection (a TCP connection plus, when TLS is enabled, a TLS handshake) to a node that has not been contacted yet. On a TLS cluster with several shards, this can add a noticeable latency spike to a freshly started application's first burst of traffic. Under constrained CPU (for example, a container that is CPU-throttled during startup) that spike can be large enough to breach command timeouts.

To avoid this, open the per-node connections before your application starts serving traffic. The upstream() node selection targets every primary node; sending a PING to the selection forces each per-node connection to be established:

RedisURI redisURI = RedisURI.Builder
        .redis("localhost")
        .withSsl(true)
        .build();

try (RedisClusterClient clusterClient = RedisClusterClient.create(redisURI)) {

    StatefulRedisClusterConnection<String, String> connection = clusterClient.connect();

    // Warm up: open a connection to every primary node before serving traffic.
    // upstream() selects all primaries; the PING forces each per-node connection to open.
    connection.sync().upstream().commands().ping();

    // If you read from replicas (ReadFrom.REPLICA / REPLICA_PREFERRED),
    // warm the replica connections too:
    // connection.sync()
    //         .readonly(node -> node.is(RedisClusterNode.NodeFlag.REPLICA))
    //         .commands().ping();

    System.out.println(connection.sync().ping());
}

Because the cluster topology can change at runtime, connections to new nodes are still opened lazily after a topology change. If you want those warmed as well, re-run the warm-up when the topology changes (for example, from a ClusterTopologyChangedEvent listener).

Warming up connections in Spring Data Redis

With Spring Data Redis, run the warm-up once at startup, before the instance is marked ready. Obtain the shared native cluster connection from the LettuceConnectionFactory and warm it with the same upstream() call:

@Component
class RedisClusterWarmUp {

    private final LettuceConnectionFactory factory;

    RedisClusterWarmUp(RedisConnectionFactory factory) {
        this.factory = (LettuceConnectionFactory) factory;
    }

    // Runs after the context starts. To keep traffic off the instance until the
    // warm-up completes, gate your readiness probe on it (for example, with a
    // HealthIndicator that reports "up" only after this method succeeds).
    @EventListener(ApplicationStartedEvent.class)
    void warmUp() {
        try (RedisClusterConnection clusterConnection = factory.getClusterConnection()) {
            @SuppressWarnings("unchecked")
            StatefulRedisClusterConnection<byte[], byte[]> connection =
                    ((RedisAdvancedClusterAsyncCommands<byte[], byte[]>) clusterConnection.getNativeConnection())
                            .getStatefulConnection();
            connection.sync().upstream().commands().ping();
        }
    }
}
Note:
The LettuceConnectionFactory eagerInitialization option is not sufficient on its own. It establishes the cluster topology and a single connection at startup, but the remaining per-node connections are still opened lazily on first use. Use the warm-up shown above to open connections to all nodes.

DNS cache and Redis

When you connect to a Redis server with multiple endpoints, such as Redis Software Active-Active, you must disable the JVM's DNS cache. If a server node or proxy fails, the IP address for any database affected by the failure will change. When this happens, your app will keep trying to use the stale IP address if DNS caching is enabled.

Use the following code to disable the DNS cache:

java.security.Security.setProperty("networkaddress.cache.ttl","0");
java.security.Security.setProperty("networkaddress.cache.negative.ttl", "0");

Exception handling

Redis handles many errors using return values from commands, but there are also situations where exceptions can be thrown. In production code, you should handle exceptions as they occur.

See the Error handling sections of the Lettuce async and Lettuce reactive API guides to learn more about handling exceptions.

Connection and execution reliability

By default, Lettuce uses an at-least-once strategy for command execution. It will automatically reconnect after a disconnection and resume executing any commands that were queued when the connection was lost. If you switch to at-most-once execution, Lettuce will not reconnect after a disconnection and will discard commands instead of queuing them. You can enable at-most-once execution by setting autoReconnect(false) in the ClientOptions when you create the client, as shown in the example below:

RedisURI uri = RedisURI.Builder
                .redis("localhost", 6379)
                .withAuthentication("default", "yourPassword")
                .build();

RedisClient client = RedisClient.create(uri);

client.setOptions(ClientOptions.builder()
    .autoReconnect(false)
        .
        .
    .build());

If you need finer control over which commands you want to execute in which mode, you can configure a replay filter to choose the commands that should retry after a disconnection. The example below shows a filter that retries all commands except for DECR (this command is not idempotent and so you might need to avoid executing it more than once). Note that replay filters are only available in Lettuce v6.6 and above.

Predicate<RedisCommand<?, ?, ?> > filter =
        cmd -> cmd.getType().toString().equalsIgnoreCase("DECR");

client.setOptions(ClientOptions.builder()
    .replayFilter(filter)
    .build());

See Command execution reliability in the Lettuce reference guide for more information.

Smart client handoffs

Smart client handoffs (SCH) is a feature of Redis Cloud and Redis Software servers that lets them actively notify clients about planned server maintenance shortly before it happens. This lets a client take action to avoid disruptions in service.

See Smart client handoffs for more information about SCH and Connect using Smart client handoffs for example code.

RATE THIS PAGE
Back to top ↑