Solução de Problemas no RabbitMQ: Diagnosticando Filas e Mensagens com Comandos

Quando uma fila do RabbitMQ parece travada, a pior primeira ação geralmente é purgá-la. A segunda pior ação é reiniciar o broker e torcer para o problema desaparecer. A maioria dos problemas de fila deixa um rastro: mensagens prontas, mensagens não confirmadas, consumidores ausentes, publishers bloqueados, mensagens não roteáveis, uma fila de mensagens mortas enchendo silenciosamente ou um consumidor conectado que não confirma nada.

Este guia usa comandos do RabbitMQ para restringir o problema a partir do terminal. Eu uso rabbitmqctl para o estado do lado do broker e rabbitmqadmin quando você precisa de operações da API de gerenciamento, como amostrar uma mensagem com segurança. Os exemplos assumem o virtual host padrão, a menos que uma opção -p <vhost> seja mostrada. Em sistemas reais, sempre inclua o vhost; muitos diagnósticos falsos acontecem porque alguém verifica / enquanto a aplicação usa payments ou prod.

Entendendo o rabbitmqctl

O comando rabbitmqctl atua como a interface de linha de comando (CLI) para interagir com a camada de gerenciamento do RabbitMQ. Ele permite gerenciar usuários, permissões, exchanges, filas, bindings e, mais importante para solução de problemas, examinar as estatísticas de tempo de execução do broker.

Nota sobre Execução: A maioria dos comandos requer privilégios de root ou que o usuário que executa o comando seja membro do grupo rabbitmq, ou você pode precisar usar sudo.

Diagnosticando Acúmulos de Filas e Mensagens Travadas

Um dos problemas mais comuns é uma fila crescendo, indicando que as mensagens estão sendo produzidas mais rápido do que estão sendo consumidas, ou que os consumidores pararam de processar.

Comece pela fila, mas peça as colunas certas

A saída padrão de list_queues é muito enxuta para solução de problemas. Peça as colunas que separam "aguardando entrega" de "entregue mas não confirmado".

rabbitmqctl -p / list_queues name messages_ready messages_unacknowledged messages consumers state

Leia assim:

Sintoma	Significado provável
messages_ready crescendo, consumers é 0	Nenhum consumidor ativo está inscrito na fila. Verifique implantações, credenciais, vhost e nome da fila.
messages_ready crescendo, consumidores presentes	Os consumidores estão muito lentos, bloqueados ou o prefetch está muito baixo para a carga de trabalho.
messages_unacknowledged alto e estável	Os consumidores receberam mensagens, mas não estão confirmando-as. Procure por handlers travados ou um valor de prefetch muito alto.
state não é running	A fila pode estar indisponível, sincronizando ou afetada por um problema de nó. Verifique o cluster e o estado do líder da fila.

Para filas quorum, adicione as colunas de líder e associação:

rabbitmqctl -p / list_queues name type leader members online messages_ready messages_unacknowledged consumers state

Isso é importante porque uma fila pode ter consumidores saudáveis em um nó enquanto o líder está em outro, ou uma fila quorum pode estar esperando que membros suficientes fiquem online.

Se a lista for longa, filtre com ferramentas de shell padrão:

rabbitmqctl -p / list_queues name messages_ready messages_unacknowledged consumers state \
  | awk '$2 > 0 || $3 > 0 || $4 == 0'

Verifique se o broker está bloqueando publishers

rabbitmqctl status
rabbitmq-diagnostics alarms

Alertas de memória e disco não significam que a fila está mal configurada, mas explicam muitos incidentes de "nada está se movendo". Quando o RabbitMQ levanta um alerta de memória ou espaço livre em disco, ele pode bloquear conexões de publicação. Os consumidores ainda podem drenar mensagens, então o sintoma visível pode ser desigual: algumas filas encolhem, outras param de receber novos trabalhos e os publishers atingem tempo limite.

Verifique também listeners e saúde do nó:

rabbitmq-diagnostics ping
rabbitmq-diagnostics listeners
rabbitmq-diagnostics check_running
rabbitmq-diagnostics check_local_alarms

Inspecione consumidores sem adivinhar

list_connections informa quem está conectado. list_channels informa se essas conexões abriram canais e quanto trabalho estão segurando.

rabbitmqctl list_connections name user peer_host peer_port state channels recv_oct send_oct
rabbitmqctl list_channels connection name number consumer_count messages_unacknowledged prefetch_count state

Os padrões úteis são simples:

• Nenhuma conexão do host esperado: a aplicação está inativa, não consegue resolver o broker, não consegue autenticar ou está se conectando a outro ambiente.
• Conexão existe, mas sem canais: o cliente conectou e falhou antes de declarar ou consumir.
• Canais existem, mas consumer_count é 0: a aplicação pode estar apenas publicando, ou a assinatura do consumidor falhou.
• messages_unacknowledged está alto em um canal: aquele consumidor tem trabalho na memória e não está retornando confirmações rapidamente.

Se você usa conexões nomeadas, inclua connection_name na configuração do seu cliente. Uma linha como 10.42.8.17:52344 -> 10.42.1.20:5672 é menos útil que billing-worker-7.

Verifique bindings antes de culpar os consumidores

Quando uma fila está vazia, mas a aplicação diz que publicou mensagens, o roteamento é o próximo lugar para olhar.

rabbitmqctl -p / list_exchanges name type durable auto_delete internal arguments
rabbitmqctl -p / list_bindings source_name source_kind destination_name destination_kind routing_key arguments

Uma exchange direta requer uma correspondência exata de chave de roteamento. Uma exchange do tipo tópico usa * para uma palavra e # para zero ou mais palavras. Uma exchange fanout ignora chaves de roteamento. Se a exchange não tem binding correspondente e nenhuma exchange alternativa, a mensagem não é roteável. Ela não está secretamente esperando em algum lugar.

Para confirmação do lado do publisher, use publicação obrigatória e trate as mensagens retornadas no cliente. No lado do broker, a interface de gerenciamento e as métricas geralmente são melhores que rabbitmqctl para taxas, mas list_bindings é suficiente para pegar os erros comuns: vhost errado, exchange errada, chave de roteamento com erro de digitação ou uma fila vinculada à exchange antiga após uma implantação.

Amostre uma mensagem com segurança

Não existe um comando geral rabbitmqctl queue_get no RabbitMQ moderno. Use o plugin de gerenciamento através de rabbitmqadmin ou da API HTTP. Faça isso com cuidado: dependendo do modo de confirmação, obter mensagens pode removê-las ou recolocá-las na fila.

rabbitmqadmin -V / get queue=orders.pending count=3 ackmode=ack_requeue_true

Use isso para responder perguntas específicas: o payload é JSON válido, o tipo de mensagem é o que o consumidor espera, falta um cabeçalho obrigatório, a chave de roteamento é a que a equipe de produção disse? Não use como ferramenta de inspeção em massa em uma fila de produção movimentada.

Procure por movimento de mensagens mortas

Processamento atrasado geralmente aparece como uma fila de mensagens mortas crescendo silenciosamente.

rabbitmqctl -p / list_queues name messages_ready messages_unacknowledged arguments policy
rabbitmqctl -p / list_bindings source_name destination_name routing_key arguments \
  | grep -E 'dead|dlx|retry|parking'

Argumentos de fila como x-dead-letter-exchange, x-dead-letter-routing-key, x-message-ttl, x-max-length e x-overflow mudam para onde as mensagens vão quando expiram, são rejeitadas ou atingem limites de comprimento. Se a aplicação tenta novamente enviando para filas de atraso através de dead-letter, um binding ruim pode criar um loop. O sintoma parece "mensagens atrasadas", mas o problema real é que as mensagens estão ciclando entre filas em vez de chegar a uma fila de processamento final ou uma fila de estacionamento.

Uma sequência prática de comandos

Quando alguém relata "pedidos estão travados", geralmente executo esta sequência:

rabbitmq-diagnostics ping
rabbitmq-diagnostics check_local_alarms
rabbitmqctl -p orders list_queues name type messages_ready messages_unacknowledged consumers state
rabbitmqctl list_connections name user peer_host state channels
rabbitmqctl list_channels connection consumer_count messages_unacknowledged prefetch_count state
rabbitmqctl -p orders list_bindings source_name destination_name routing_key arguments

Se messages_ready está alto e consumers é zero, vá para a implantação do consumidor. Se messages_unacknowledged está alto, vá para os logs do consumidor e configurações de prefetch. Se a fila está vazia, mas os publishers relatam sucesso, inspecione bindings e confirmações do publisher. Se alertas estão ativos, corrija a pressão de recursos do broker antes de perseguir a lógica da aplicação. Isso mantém a investigação baseada no que o broker está realmente fazendo.