Nesta página
A sua equipe abre INFO server, INFO clients, INFO memory — tudo parece normal. A CPU está baixa. A memória está dentro dos limites. Nenhuma entrada no slow log. Mesmo assim, a aplicação continua lançando exceções de timeout do Redis, e os serviços que dependem dele estão degradando ou falhando.
Esse é um modo de falha realmente comum e realmente confuso, porque o instinto é olhar primeiro para o servidor. Nos casos em que atuamos, o problema quase nunca está no servidor.
Onde procurar de verdade quando há timeouts no Redis, mas o servidor está bem?
Em três lugares, por ordem de probabilidade:
- A configuração do cliente — especificamente os valores de timeout, o tamanho do connection pool e o comportamento de retry.
- O caminho de rede — firewalls, load balancers ou dispositivos de NAT entre a sua aplicação e o Redis que derrubam silenciosamente conexões ociosas.
- Chaves grandes ou comandos bloqueantes — operações que bloqueiam o event loop single-threaded do Redis por tempo suficiente para causar timeouts no cliente, mesmo que o servidor nunca "caia".
Um caso real de produção deixa isso concreto: um projeto com um cliente teve todo o escopo definido em torno de um timeout de 10 segundos no cliente que causava interrupções em microsserviços. A investigação confirmou que os erros ocorriam do lado do cliente, e não nos servidores Redis — o servidor não tinha registrado nenhum erro ou lentidão equivalente. A causa raiz exigiu uma análise mais profunda dos padrões de esgotamento de recursos do lado do cliente e da aplicação, e não da instância Redis em si.
As minhas conexões caem sempre durante uma janela de manutenção específica: o que está acontecendo?
Esse é um sintoma da camada de rede, e é mais comum do que as equipes imaginam em ambientes de nuvem e redes corporativas com manutenções de firewall agendadas.
Em um dos casos, eventos de manutenção do firewall faziam todas as conexões TCP com o cluster Redis caírem ao mesmo tempo; a janela de manutenção durava de três a cinco minutos e resultava em uma indisponibilidade total da rede, que exigia restart manual das aplicações. Não era um problema do Redis — era a infraestrutura no caminho de rede entre a aplicação e o Redis encerrando silenciosamente as conexões estabelecidas durante um upgrade rotineiro do firewall.
Como confirmar se esse é o seu problema:
- Verifique se os incidentes de timeout coincidem com um horário recorrente (toda noite, toda semana), e não com padrões de carga
- Pergunte diretamente à sua equipe de rede se existem janelas de manutenção agendadas de firewall, load balancer ou NAT gateway
- Se possível, capture o tráfego durante a janela — um TCP RST limpo ou uma queda silenciosa da conexão, sem nenhuma entrada correspondente no log do servidor Redis, confirma que quem age é a camada de rede, e não o Redis
Quais configurações do cliente realmente resolvem os timeouts do Redis?
Duas configurações importam mais, e foram exatamente a correção aplicada em uma remediação real: TCP keepalive e ajuste de retry e timeout no nível do cliente.
TCP keepalive. Sem o keepalive habilitado, conexões ociosas atrás de um firewall ou dispositivo de NAT são fortes candidatas a encerramento silencioso — a pilha TCP do sistema operacional não sabe que a conexão caiu até tentar usá-la, e nesse momento você recebe um timeout em vez de uma reconexão limpa. Habilitar o TCP keepalive com um intervalo razoavelmente agressivo (bem abaixo do timeout de conexões ociosas do firewall/NAT) mantém a conexão viva com pacotes periódicos sem efeito, ou faz a falha aparecer rápido o suficiente para que o connection pool recicle a conexão morta antes de a aplicação tentar usá-la.
Configuração de retry e timeout na biblioteca cliente. Em aplicações Java que usam o cliente Redis Lettuce (comum com Spring Data Redis), isso significa configurar explicitamente:
- O timeout de comando (quanto tempo esperar por uma resposta do Redis antes de desistir)
- As opções de keepalive no nível do socket na própria biblioteca cliente, e não só no sistema operacional
- A política de retry para falhas de conexão transitórias, distinguindo entre "connection refused" (falhar rápido) e "connection reset" (seguro tentar de novo)
Um projeto de remediação em produção gerou especificamente um relatório resumido com as configurações recomendadas de TCP keepalive e de retry para o servidor e para o cliente, seguido de orientações diretas de ajuste da configuração do cluster Redis do cliente e dos parâmetros de timeout e retry do Lettuce.
As chaves grandes podem ser a causa dos timeouts?
Sim — e vale a pena descartar essa hipótese mesmo que você já tenha encontrado um fator de rede ou do cliente, porque chaves grandes podem agravar o problema.
O Redis é single-threaded na execução de comandos. Um comando que opera sobre uma chave muito grande (um hash enorme, um sorted set gigantesco, uma string grande) pode bloquear o event loop por tempo suficiente para que os comandos de outros clientes se acumulem na fila e acabem dando timeout, mesmo que o servidor "pareça" saudável nas métricas agregadas de CPU e memória.
A investigação desse padrão explorou especificamente técnicas de compressão para chaves grandes do Redis como possível otimização de desempenho, junto com as correções na camada de rede — porque, em implantações reais, a causa raiz do timeout muitas vezes não é um único fator, mas a combinação de uma rede de confiabilidade marginal com operações ocasionais em chaves grandes que empurram a latência para além do limite de timeout do cliente.
Como verificar: rode redis-cli --bigkeys durante um período de tráfego representativo ou use MEMORY USAGE <key> nas chaves suspeitas. Se encontrar chaves na faixa de vários megabytes sendo acessadas com comandos como HGETALL, SMEMBERS ou LRANGE sem limites, você tem um forte candidato.
Qual é a forma sistemática de diagnosticar isso, sem chutar?
Percorra os passos nesta ordem:
- Confirme que o problema está no cliente. Verifique os logs do servidor Redis e a saída do
INFOem busca de qualquer coisa que coincida com a janela do timeout. Se o servidor não mostrar nada, você confirmou que o problema está antes do próprio Redis. - Procure correlação com algum horário. Acontece em uma hora do dia ou em um dia da semana específico? Isso aponta para manutenção da infraestrutura de rede.
- Revise a configuração do cliente. Timeout de comando, tamanho do connection pool, configurações de TCP keepalive — compare com a tolerância real do seu caminho de rede a conexões ociosas.
- Descarte chaves grandes e comandos bloqueantes. Rode
--bigkeyse revise os seus padrões de comandos em busca de qualquer coisa que opere sobre coleções sem limite. - Capture evidências no nível de pacotes se os passos anteriores não resolverem. Uma captura de tráfego durante uma janela de reprodução mostra de forma definitiva se a conexão está sendo resetada por um dispositivo de rede ou dando timeout no cliente.
Uma equipe de infraestrutura generalista consegue diagnosticar isso, ou é preciso expertise específica em Redis?
A expertise específica em Redis faz muita diferença, principalmente porque o sintoma (timeout) parece idêntico seja a causa no Redis, no cliente ou na rede, e equipes sem experiência operacional profunda em Redis muitas vezes começam ajustando a camada errada — normalmente o servidor, já que é o componente com "Redis" no nome.
Os dois casos de produção citados neste post exigiram coordenação entre equipes — times de aplicação/DevOps trabalhando junto com especialistas em Redis e, no caso do firewall, diretamente com a equipe de redes/segurança — para isolar a camada realmente responsável. É exatamente nesse tipo de processo de diagnóstico multifuncional que uma avaliação estruturada de Redis mostra o seu valor: ela não parte do princípio de que a resposta é "ajustar o Redis" e, em vez disso, rastreia a falha até onde ela realmente está.
Um diagnóstico de dez minutos para timeouts do Redis
Esta é a ordem em que rodamos os comandos e o que cada resposta confirma ou descarta. Tudo isso também vale para o Valkey.
redis-cli --latencya partir do host do cliente e, depois, do host do servidor. Rode--latency-historynos dois por alguns minutos. Picos só no host do cliente indicam o caminho de rede ou a máquina do cliente; nada no Redis vai resolver isso. Picos nos dois indicam que o servidor está travando, então siga adiante nesta lista.
SLOWLOG GET 25eINFO commandstats. O slowlog mostra comandos individuais que excederamslowlog-log-slower-than(10 ms por padrão). O commandstats mostra ousec_per_callpor tipo de comando, o que pega umKEYScom média de 40 ms mesmo quando nenhuma chamada isolada chegou ao slowlog. Os culpados de sempre sãoKEYS,SMEMBERSem um set grande,HGETALLem um hash largo, operações de conjunto no estiloSUNIONe scripts Lua com loops. Cada um deles bloqueia todos os outros clientes durante toda a sua execução.
INFO clients.blocked_clientsacima de zero é normal comBLPOPou streams; fora isso, algo está esperando por uma chave que nunca chega. Compareclient_recent_max_output_buffercomCONFIG GET client-output-buffer-limit: um subscriber ou uma réplica lenta enche o buffer, o limite estoura e o servidor derruba a conexão, o que o cliente reporta como timeout.
INFO persistence. Comparerdb_bgsave_in_progress,aof_rewrite_in_progresselatest_fork_useccom os horários dos timeouts. Um fork em um dataset grande pausa a thread principal por centenas de milissegundos, e o copy-on-write que vem em seguida deixa todas as escritas mais lentas. Timeouts no mesmo minuto de toda hora são quase sempre umBGSAVEagendado.
INFO stats. Um salto emevicted_keyssignifica que você atingiu omaxmemorye o servidor está gastando o seu tempo escolhendo vítimas; um salto emexpired_keyssignifica um precipício de TTL, em que muitas chaves expiram no mesmo segundo. Qualquer um dos dois trava o event loop. O nosso guia de memória do Redis e a FAQ sobre memória que cresce sem aumento de chaves cobrem as correções.
CLIENT LIST. Conte as conexões poraddrename. Um pool travado no limite enquanto as requisições se acumulam significa que o "timeout" é o tempo gasto esperando uma conexão livre, e não uma resposta lenta.qbufouomemaltos em uma única entrada apontam para um cliente específico com mau comportamento.
- O host. Em uma VM,
vmstat 1com a coluna de steal diferente de zero significa que o hypervisor está tomando a sua CPU.cat /sys/kernel/mm/transparent_hugepage/enableddeve retornarnever; o Redis e o Valkey alertam sobre isso na inicialização porque o THP aumenta as pausas de fork. Qualquer uso de swap em um host Redis é um achado.
- As configurações do cliente por último. Só agora olhe para o tamanho do pool, o timeout do socket e a política de retry. Comece por aqui e você vai aumentar o timeout, esconder o sintoma e voltar ao problema em um mês.
No nosso trabalho de suporte, o passo 2 encontra a causa mais vezes do que todos os outros somados, com o passo 4 em um claro segundo lugar. Causas de rede são menos comuns do que as pessoas imaginam, e é por isso que o passo 1 resolve essa dúvida em dois minutos. Para um runbook mais completo, veja troubleshooting do Redis.
Erros de timeout por cliente e o que eles costumam significar
- Jedis.
JedisConnectionException: Could not get a resource from the poolé esgotamento do pool: conexões que não são devolvidas (falta declose()ou de try-with-resources) oumaxTotalbaixo demais para a quantidade de threads.JedisConnectionExceptionencapsulandoSocketTimeoutException: Read timed outé um timeout de leitura, muitas vezes o padrão de 2.000 ms atingido por um único comando lento do passo 2. - Lettuce.
RedisCommandTimeoutException: Command timed out after 1 minute(s)é o padrão de 60 segundos, e é por isso que as requisições do Lettuce ficam penduradas em vez de falhar rápido. O Lettuce multiplexa os comandos em uma única conexão, então um único comando lento segura a fila para todos que vêm atrás dele. Durante uma reconexão, os comandos se acumulam em memória e depois dão timeout em rajada. - StackExchange.Redis.
RedisTimeoutException: Timeout performing GET (5000ms), inst: 0, qu: 0, qs: 12, aw: False, in: 65536, ...se lê assim:qssão os comandos enviados que aguardam resposta,qusão os comandos ainda não escritos,insão os bytes já recebidos mas ainda não processados, emgrmostra o estado do socket manager.inalto comqsalto significa que a resposta chegou e o cliente não conseguiu lê-la, o que é starvation do thread pool, normalmente causada por bloqueio em.Resultou.Wait()no código de requisições web. Confira a linhaWORKERna mesma mensagem: busy acima de min é a confirmação. - node-redis e ioredis. Os dois separam o timeout de conexão do comportamento dos comandos. O ioredis tem
connectTimeout,commandTimeoutemaxRetriesPerRequest(20 por padrão), entãoMaxRetriesPerRequestErrorsignifica que o loop de reconexão desistiu, e não que o Redis estava lento. UmaretryStrategyque retorna um atraso curto para sempre produz uma enxurrada de logs e nunca revela o erro real. O node-redis usareconnectStrategye, em versões mais antigas, não tem timeout por comando, então um servidor travado produz promises penduradas em vez de erros. - redis-py.
socket_connect_timeoutlimita o handshake TCP;socket_timeoutlimita cada leitura e, por padrão, não tem valor, então uma chamada travada espera para sempre.TimeoutError: Timeout reading from socketé este último caso.health_check_intervalenvia umPINGantes de reutilizar uma conexão ociosa, o que resolve oConnectionError: Connection closed by serverdepois que um firewall derruba sockets ociosos. - Clientes Go.
context deadline exceededé o context de quem chama, e não o timeout do próprio cliente, então verifique os dois.redis: connection pool timeoutsignifica que há mais goroutines do que oPoolSizee elas esperaram além doPoolTimeoutpor uma conexão livre; aumente o pool ou encontre o vazamento de goroutines.
Se você prefere entregar isso a quem faz esse trabalho todos os dias, a nossa equipe de suporte Redis fica de plantão 24/7, com metas de resposta a partir de 15 minutos, conforme o plano, e a consultoria Redis corrige o design por trás do problema.
Ajuda com timeouts e problemas de conexão no cliente Redis
Enfrentando timeouts do Redis que não coincidem com nada visível nas métricas do servidor? Esse é exatamente o tipo de problema em camadas — cliente, rede ou servidor — que uma avaliação estruturada de Redis foi feita para isolar, sem chute. A AceMQ oferece suporte Redis corporativo para ambientes de produção. Fale com um engenheiro da AceMQ.
Este é o passo quatro de sete do guia de confiabilidade do Redis, que trata os problemas na ordem em que eles aparecem em um ambiente de produção.
Perguntas frequentes
Onde procurar quando há timeouts no Redis, mas as métricas do servidor parecem saudáveis?
Em três lugares, por ordem de probabilidade: a configuração do cliente (valores de timeout, tamanho do connection pool, comportamento de retry), o caminho de rede (firewalls, load balancers ou dispositivos de NAT que derrubam silenciosamente conexões ociosas) e chaves grandes ou comandos bloqueantes que travam o event loop single-threaded. Em um caso real de produção, um timeout de 10 segundos no cliente foi atribuído inteiramente ao esgotamento de recursos do lado do cliente, sem nenhum erro ou lentidão correspondente do lado do servidor.
Por que as minhas conexões com o Redis caem durante uma janela de manutenção específica?
Isso é quase sempre um sintoma da camada de rede, e não um problema do Redis. Manutenções agendadas de firewall, load balancer ou NAT gateway podem encerrar silenciosamente conexões TCP estabelecidas com o seu cluster Redis. Para confirmar, verifique se os incidentes coincidem com um horário recorrente, e não com a carga, e pergunte diretamente à sua equipe de rede sobre as janelas de manutenção.
Quais configurações do cliente realmente resolvem os timeouts do Redis?
TCP keepalive e o ajuste de retry e timeout no nível do cliente são as duas configurações que mais importam. Habilitar o TCP keepalive com um intervalo menor que o timeout de conexões ociosas do firewall ou do NAT evita o encerramento silencioso da conexão, e configurar o timeout de comando, o keepalive no nível do socket e a política de retry na biblioteca cliente (como o Lettuce, para Java/Spring) fecha o resto da lacuna.
Chaves grandes podem estar causando os timeouts do Redis?
Sim. O Redis é single-threaded na execução de comandos, então um comando sobre um hash, sorted set ou string muito grande pode bloquear o event loop por tempo suficiente para que os comandos de outros clientes se acumulem na fila e deem timeout. Rode redis-cli --bigkeys ou MEMORY USAGE <key> para verificar e fique de olho em HGETALL, SMEMBERS ou LRANGE usados sem limites em chaves de vários megabytes.
Qual é a forma sistemática de diagnosticar um timeout no cliente Redis?
Confirme que o problema está no cliente verificando os logs do servidor Redis e a saída do INFO em busca de qualquer coisa que coincida com a janela do timeout. Depois, procure correlação com algum horário, revise a configuração do cliente em relação à tolerância a conexões ociosas do seu caminho de rede, descarte chaves grandes e comandos bloqueantes e capture evidências no nível de pacotes se o problema persistir.
Diagnosticar timeouts do Redis exige expertise específica em Redis?
Faz muita diferença ter, porque um timeout parece idêntico seja a causa no Redis, no cliente ou na rede, e equipes sem experiência em Redis costumam começar ajustando o servidor. Os dois casos de produção citados neste post exigiram coordenação entre as equipes de aplicação, DevOps e rede para isolar a camada realmente responsável.