Solução de Problemas Comuns de Conexão Redis e Timeouts de Cliente

Os erros de conexão Redis são ruidosos porque o mesmo sintoma de aplicação pode vir de várias camadas. Uma solicitação pode falhar porque a conexão TCP nunca alcançou o Redis, porque o Redis aceitou a conexão mas não tinha slots de cliente livres, porque um comando lento bloqueou o loop de eventos tempo suficiente para o cliente desistir, ou porque a aplicação esgotou seu próprio pool de conexões.

Trate o texto exato do erro como a primeira pista. Connection refused geralmente significa que o host respondeu mas nada aceitou a conexão naquela porta. Connection timed out geralmente significa que o caminho do pacote está bloqueado ou muito lento. Um erro Redis LOADING significa que o servidor está ativo mas ainda restaurando dados. ERR max number of clients reached aponta diretamente para limites de conexão do lado do servidor. Um timeout do lado do cliente após um comando ser enviado geralmente aponta para latência, comandos lentos, ou fome de pool.

Diagnosticando a Causa Raiz: Por Onde Começar

Comece com a camada que pode ser verificada mais rapidamente: o servidor está ouvindo, o cliente consegue alcançá-lo, o Redis está respondendo, e os clientes estão expirando enquanto esperam por uma resposta de comando?

1. Verificações de Rede e Firewall

Falhas de conectividade são frequentemente as mais simples de resolver. Garanta que os caminhos básicos de rede estejam abertos e estáveis.

A. Acessibilidade da Porta

Verifique se o Redis está ouvindo no endereço e porta esperados. A porta padrão é 6379, mas serviços Redis gerenciados, contêineres e implantações reforçadas frequentemente usam caminhos de rede diferentes.

Passo Acionável (Verificação no Servidor Linux): Use ss no host Redis:

# Verificar status de escuta na porta padrão
ss -tuln | grep 6379
# Exemplo se estiver ouvindo publicamente:
# tcp LISTEN 0 511 0.0.0.0:6379 0.0.0.0:*

Ouvir em 127.0.0.1:6379 é correto para um Redis apenas local, mas clientes remotos não conseguirão conectar. Ouvir em 0.0.0.0 pode ser necessário dentro de uma rede privada, mas não exponha o Redis diretamente à internet pública. Use rede privada, regras de firewall, autenticação e TLS quando apropriado.

B. Latência e Perda de Pacotes

Do host do cliente, teste a porta diretamente:

nc -vz redis.example.internal 6379
redis-cli -h redis.example.internal -p 6379 PING

PONG prova mais do que uma porta TCP aberta; prova que o Redis aceitou e processou um comando. Se nc funciona mas redis-cli PING não, verifique autenticação, requisitos TLS, modo protegido do Redis e latência de comando.

Para timeouts intermitentes, use mtr, métricas de rede em nuvem ou capturas de pacotes para procurar perda de pacotes e mudanças de roteamento. Um servidor Redis pode estar saudável enquanto uma zona de disponibilidade, gateway NAT, sidecar de malha de serviço ou caminho de firewall está causando timeouts visíveis ao cliente.

2. Restrições de Recursos do Servidor Redis

O Redis processa a maioria dos comandos em um único caminho principal de execução. Um comando caro pode fazer clientes não relacionados esperarem. Essa espera geralmente aparece como timeouts de cliente em vez de erros óbvios do Redis.

A. Limite de Conexões Máximas (maxclients)

Quando o Redis atinge maxclients, novos clientes podem receber um erro como ERR max number of clients reached. Algumas bibliotecas de aplicação exibem isso mal, então verifique também as métricas do Redis.

Se o cliente receber um erro de recusa imediatamente ao tentar conectar, verifique a configuração do servidor:

CONFIG GET maxclients

Também inspecione os clientes atuais:

redis-cli INFO clients
redis-cli CLIENT LIST

Se connected_clients cresce sem diminuir, suspeite de vazamentos de conexão, muitos processos de trabalho, falta de pooling ou verificações de saúde criando novas conexões com muita frequência. Aumentar maxclients pode ganhar tempo, mas também aumenta o uso de memória. Corrija o comportamento do cliente se a contagem for ilimitada.

B. Comandos Lentos e Operações Bloqueantes

Comandos de longa duração como KEYS *, HGETALL grande, SMEMBERS grande, scripts Lua pesados e exclusões enormes podem bloquear outros trabalhos. A persistência também pode adicionar latência, especialmente se o host estiver com pouca CPU, memória ou largura de banda de disco.

Diagnóstico usando o Slow Log: O Redis fornece um poderoso Slow Log para rastrear comandos que excedem um tempo de execução definido (slowlog-log-slower-than).

1. Verificar Configuração:

   CONFIG GET slowlog-log-slower-than
   CONFIG GET slowlog-max-len
   

2. Visualizar Entradas do Log:

   SLOWLOG GET 10  # Exibir as últimas 10 entradas lentas
   

Se as entradas do slow log coincidirem com timeouts de cliente, corrija o padrão de comando. Use SCAN em vez de KEYS, HSCAN em vez de leituras completas de hash, UNLINK em vez de DEL para chaves muito grandes e paginação em vez de buscar coleções inteiras.

C. Impacto da Persistência (AOF/RDB)

E/S de disco relacionada a fsync AOF, reescrita AOF ou snapshot RDB pode adicionar latência. O efeito é pior quando o Redis compartilha um disco com logs, backups, outros bancos de dados ou um nó de contêiner ruidoso.

Verifique:

redis-cli INFO persistence
redis-cli LATENCY LATEST

Se os timeouts ocorrerem durante BGSAVE ou BGREWRITEAOF, deixe mais margem de memória, reduza a rotatividade de escrita durante esses períodos, mova o Redis para armazenamento mais rápido ou ajuste o tempo de persistência. Não desative a persistência simplesmente, a menos que os dados sejam realmente descartáveis.

Configuração do Lado do Cliente e Gerenciamento de Timeout

As bibliotecas de cliente oferecem parâmetros para gerenciar pooling de conexão e expectativas de timeout. Clientes configurados incorretamente são uma fonte frequente de instabilidade percebida do servidor.

1. Otimizando Timeouts do Cliente

Os timeouts do cliente definem quanto tempo a aplicação espera por uma resposta antes de desistir. Se o servidor estiver lento, o cliente deve esperar tempo suficiente, mas não indefinidamente.

• Timeout curto: Útil para leituras de cache onde a aplicação pode cair com segurança para um banco de dados ou resposta padrão.
• Timeout longo: Útil para operações onde tentar novamente agressivamente pioraria o incidente, mas pode ocupar threads de solicitação se o Redis estiver não saudável.

Escolha timeouts com base no comportamento da aplicação. Se o Redis é um cache de melhor esforço, falhe rápido e degrade graciosamente. Se o Redis é necessário para sessões de login, o timeout pode precisar ser maior, mas você também deve ter um disjuntor para que um incidente Redis não consuma todos os workers web.

2. Pooling de Conexão e Vazamentos

Pools de conexão gerenciados inadequadamente podem levar ao esgotamento de slots disponíveis do servidor ou clientes mantendo conexões obsoletas.

• Esgotamento do Pool: Se o tamanho do pool for muito pequeno, as solicitações se enfileiram, potencialmente levando a timeouts no nível da aplicação, mesmo que o servidor Redis esteja saudável.
• Vazamentos de Conexão: Se as conexões são abertas mas nunca retornadas ao pool após o uso, o pool se esgota e novas solicitações falham ao conectar.

Verifique as métricas do pool na aplicação, não apenas no Redis. Você quer saber conexões ativas, conexões ociosas, tempo de espera por uma conexão do pool, falhas ao pegar uma conexão e contagem de reconexões. Um servidor Redis saudável não pode ajudar se toda thread da aplicação está esperando por um pool subdimensionado.

3. Lidando com Desconexões e Estratégias de Reconexão

Pequenos problemas de rede causam desconexões transitórias. Um cliente robusto deve lidar graciosamente com esses eventos.

Use backoff exponencial com jitter para reconexões. Quando centenas de workers de aplicação reconectam ao mesmo tempo após um problema de rede, um loop de retry imediato pode criar uma segunda interrupção.

1. Espere um curto período (ex.: 1 segundo) e tente novamente.
2. Se falhar novamente, dobre o tempo de espera (2 segundos, 4 segundos, etc.).
3. Limite o tempo total de retry com base nos requisitos de negócio.

A maioria dos clientes maduros lida com reconexão básica, mas os padrões variam. Verifique se os comandos são enfileirados durante a reconexão, se os retries podem duplicar escritas e se seu framework esconde erros Redis até que a latência da solicitação já esteja alta.

Uma ordem prática de solução de problemas

Use esta ordem durante um incidente:

Passo	Área	Verificação/Ação	Sintoma Correspondente
1	Servidor ouvindo	ss -tuln, status do serviço Redis	Conexão recusada
2	Limites do Servidor	CONFIG GET maxclients	Conexão Recusada
3	Desempenho do Servidor	SLOWLOG GET	Timeouts Intermitentes
4	Persistência	Verificar atividade BGSAVE/BGREWRITEAOF	Picos de Latência/Timeouts
5	Configuração do Cliente	Revisar configurações de timeout do cliente e tamanho do pool	Erros do Lado do Cliente

A correção mais útil de timeout Redis raramente é "aumentar o timeout" por si só. Às vezes é necessário, mas deve vir depois que você souber se o atraso é devido à acessibilidade de rede, limites do servidor, comandos lentos, pressão de persistência ou fome de pool. Corrija a camada que está realmente falhando, então ajuste o timeout para que a aplicação se comporte previsivelmente na próxima vez que o Redis estiver lento.