Dépannage de RabbitMQ : Diagnostiquer les problèmes de files d'attente et de messages avec des commandes

Lorsqu'une file d'attente RabbitMQ semble bloquée, la pire première action est généralement de la vider. La deuxième pire action est de redémarrer le courtier en espérant que le problème se résolve. La plupart des problèmes de file d'attente laissent une trace : messages prêts, messages non acquittés, consommateurs manquants, éditeurs bloqués, messages non routables, une file d'attente de lettres mortes qui se remplit silencieusement, ou un consommateur connecté mais n'acquittant rien.

Ce guide utilise les commandes RabbitMQ pour réduire cela depuis le terminal. Je m'appuie sur rabbitmqctl pour l'état côté courtier et rabbitmqadmin lorsque vous avez besoin d'opérations d'API de gestion telles que l'échantillonnage sécurisé d'un message. Les exemples supposent l'hôte virtuel par défaut sauf si une option -p <vhost> est affichée. Dans les systèmes réels, incluez toujours le vhost ; de nombreux diagnostics erronés se produisent parce que quelqu'un vérifie / alors que l'application utilise payments ou prod.

Comprendre `rabbitmqctl`

La commande rabbitmqctl agit comme l'interface en ligne de commande (CLI) pour interagir avec la couche de gestion RabbitMQ. Elle vous permet de gérer les utilisateurs, les permissions, les échanges, les files d'attente, les liaisons et, surtout pour le dépannage, d'examiner les statistiques d'exécution du courtier.

Remarque sur l'exécution : La plupart des commandes nécessitent des privilèges root ou que l'utilisateur exécutant la commande soit membre du groupe rabbitmq, ou vous devrez peut-être utiliser sudo.

Diagnostiquer les arriérés de files d'attente et les messages bloqués

L'un des problèmes les plus courants est une file d'attente qui croît, indiquant que les messages sont produits plus rapidement qu'ils ne sont consommés, ou que les consommateurs ont cessé de traiter.

Commencez par la file d'attente, mais demandez les bonnes colonnes

La sortie par défaut de list_queues est trop légère pour le dépannage. Demandez les colonnes qui séparent "en attente de livraison" de "livré mais non acquitté".

rabbitmqctl -p / list_queues name messages_ready messages_unacknowledged messages consumers state

Lisez-le comme ceci :

Symptôme	Signification probable
`messages_ready` croît, `consumers` est `0`	Aucun consommateur actif n'est abonné à la file d'attente. Vérifiez les déploiements, les identifiants, le vhost et le nom de la file d'attente.
`messages_ready` croît, consommateurs présents	Les consommateurs sont trop lents, bloqués, ou la prélecture est trop faible pour la charge de travail.
`messages_unacknowledged` élevé et stable	Les consommateurs ont reçu des messages mais ne les acquittent pas. Recherchez des gestionnaires bloqués ou une valeur de prélecture trop élevée.
`state` n'est pas `running`	La file d'attente peut être indisponible, en cours de synchronisation, ou affectée par un problème de nœud. Vérifiez l'état du cluster et du leader de la file d'attente.

Pour les files d'attente de quorum, ajoutez les colonnes leader et appartenance :

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

Cela compte car une file d'attente peut avoir des consommateurs sains sur un nœud tandis que le leader est ailleurs, ou une file d'attente de quorum peut attendre que suffisamment de membres soient en ligne.

Si la liste est longue, filtrez avec des outils shell standard :

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

Vérifiez si le courtier bloque les éditeurs

rabbitmqctl status
rabbitmq-diagnostics alarms

Les alarmes de mémoire et de disque ne signifient pas que la file d'attente est mal configurée, mais elles expliquent de nombreux incidents "rien ne bouge". Lorsque RabbitMQ déclenche une alarme de mémoire ou d'espace disque libre, il peut bloquer les connexions de publication. Les consommateurs peuvent encore drainer les messages, donc le symptôme visible peut être inégal : certaines files d'attente rétrécissent, d'autres cessent de recevoir de nouveaux travaux, et les éditeurs expirent.

Vérifiez également les écouteurs et la santé des nœuds :

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

Inspectez les consommateurs sans deviner

list_connections vous indique qui est connecté. list_channels vous indique si ces connexions ont ouvert des canaux et combien de travail elles détiennent.

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

Les modèles utiles sont simples :

Aucune connexion de l'hôte attendu : l'application est en panne, ne peut pas résoudre le courtier, ne peut pas s'authentifier, ou se connecte à un autre environnement.
Connexion existe, mais aucun canal : le client s'est connecté puis a échoué avant de déclarer ou de consommer.
Canaux existent, mais consumer_count est 0 : l'application peut être en publication uniquement, ou l'abonnement du consommateur a échoué.
messages_unacknowledged est élevé sur un canal : ce consommateur a du travail en mémoire et ne renvoie pas les acquittements rapidement.

Si vous utilisez des connexions nommées, incluez connection_name dans votre configuration client. Une ligne comme 10.42.8.17:52344 -> 10.42.1.20:5672 est moins utile que billing-worker-7.

Vérifiez les liaisons avant de blâmer les consommateurs

Lorsqu'une file d'attente est vide mais que l'application dit avoir publié des messages, le routage est le prochain endroit à vérifier.

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

Un échange direct nécessite une correspondance exacte de la clé de routage. Un échange de sujet utilise * pour un mot et # pour zéro ou plusieurs mots. Un échange de diffusion ignore les clés de routage. Si l'échange n'a pas de liaison correspondante et aucun échange alternatif, le message n'est pas routable. Il n'attend pas secrètement quelque part.

Pour la confirmation côté éditeur, utilisez la publication obligatoire et gérez les messages retournés dans le client. Côté courtier, l'interface utilisateur de gestion et les métriques sont généralement meilleures que rabbitmqctl pour les taux, mais list_bindings suffit pour attraper les erreurs courantes : mauvais vhost, mauvais échange, clé de routage mal orthographiée, ou une file d'attente liée à l'ancien échange après un déploiement.

Échantillonnez un message en toute sécurité

Il n'y a pas de commande générale rabbitmqctl queue_get dans RabbitMQ moderne. Utilisez le plugin de gestion via rabbitmqadmin ou l'API HTTP. Faites-le avec précaution : selon le mode d'acquittement, obtenir des messages peut les supprimer ou les remettre en file d'attente.

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

Utilisez ceci pour répondre à des questions précises : le payload est-il un JSON valide, le type de message est-il celui attendu par le consommateur, un en-tête requis est-il manquant, la clé de routage est-elle celle que l'équipe productrice a dit qu'elle était ? Ne l'utilisez pas comme un outil d'inspection en masse sur une file d'attente de production occupée.

Recherchez les mouvements de lettres mortes

Un traitement retardé se manifeste souvent par une file d'attente de lettres mortes qui croît silencieusement.

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'

Les arguments de file d'attente tels que x-dead-letter-exchange, x-dead-letter-routing-key, x-message-ttl, x-max-length, et x-overflow changent l'endroit où les messages vont lorsqu'ils expirent, sont rejetés ou atteignent les limites de longueur. Si l'application réessaie en mettant en lettre morte via des files d'attente de délai, une mauvaise liaison peut créer une boucle. Le symptôme ressemble à "messages retardés", mais le vrai problème est que les messages tournent entre les files d'attente au lieu d'atteindre une file d'attente de traitement final ou une file d'attente de parking.

Une séquence de commandes pratique

Quand quelqu'un signale "les commandes sont bloquées", j'exécute généralement cette séquence :

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

Si messages_ready est élevé et consumers est zéro, allez voir le déploiement du consommateur. Si messages_unacknowledged est élevé, allez voir les journaux du consommateur et les paramètres de prélecture. Si la file d'attente est vide mais que les éditeurs signalent un succès, inspectez les liaisons et les confirmations d'éditeur. Si des alarmes sont actives, corrigez la pression sur les ressources du courtier avant de chercher la logique applicative. Cela maintient l'investigation ancrée dans ce que le courtier fait réellement.