Sur cette page
Lancez deux commandes avant d'échafauder une hypothèse
Lancez deux commandes avant d'échafauder une hypothèse
rabbitmq-diagnostics alarms vous indique si le broker a cessé d'accepter les publications, et rabbitmqctl list_queues -p <vhost> name messages consumers vous indique si quelque chose consomme. Une file d'attente qui grossit sans aucun consommateur est de loin le ticket « RabbitMQ est en panne » le plus fréquent que nous recevons, et la correction se trouve presque toujours dans l'application consommatrice. Repérez ensuite votre symptôme :
| Symptôme | Première vérification |
|---|---|
| File d'attente qui grossit sans se vider | rabbitmqctl list_queues avec consumers et unacked |
| Alarme mémoire, éditeurs bloqués | rabbitmq-diagnostics memory_breakdown |
| Alarme disque | rabbitmq-diagnostics status, espace disque libre par rapport à la limite |
| Partition ou nœud injoignable | rabbitmq-diagnostics cluster_status |
| Nœud qui ne démarre pas ou ne rejoint pas le cluster | rabbitmq-diagnostics log_tail |
| Les clients ne peuvent pas se connecter | rabbitmq-diagnostics listeners |
| Lien de fédération ou Shovel tombé | rabbitmqctl federation_status --only-down |
| Messages publiés mais jamais reçus | rabbitmqctl list_bindings |
| Pods bloqués sur Kubernetes | kubectl describe pod |
À quoi sert cette page et ce qu'elle suppose
Il s'agit d'une table de correspondance entre symptômes et vérifications, pas d'un runbook : chaque section donne une première vérification et un tableau qui explique le résultat. Le runbook d'incident contient les séquences de commandes complètes et ordonnées pour les alarmes disque et mémoire, les partitions, la perte de quorum et la reprise d'un datacenter, et le guide des schémas de défaillance explique pourquoi chacun se produit. Servez-vous de cette page pour déterminer lequel il vous faut.
Elle suppose RabbitMQ 4.x. Depuis la 4.3.0, le metadata store est exclusivement Khepri et les anciennes stratégies de gestion des partitions ont disparu : les branches consacrées aux partitions sont donc rédigées pour Raft ; lorsqu'un cluster 4.2 ou antérieur se comporte différemment, la ligne le précise. Les symptômes sont ceux qui arrivent réellement au support AceMQ, tirés de nos tickets plutôt que d'une liste générique.
Une file d'attente grossit et ne se vide pas
Vérifiez avant tout le nombre de consommateurs sur cette file d'attente : c'est lui qui indique si le problème vient du broker ou de l'application.
rabbitmqctl list_queues -p <vhost> name type messages messages_unacknowledged consumers| Si vous constatez | Cela signifie généralement | Que faire |
|---|---|---|
| Consumers vaut 0 | Rien ne consomme. L'application consommatrice est arrêtée, a planté ou n'a pas réussi à se reconnecter après un redémarrage. | Vérifiez l'application, pas le cluster. Le broker fait son travail. |
| Consumers supérieur à 0, unacked élevé et figé | Les consommateurs détiennent des messages qu'ils n'acquittent jamais, généralement bloqués sur un appel aval sans timeout, ou sur un chemin de code qui n'acquitte jamais. | Redémarrez les consommateurs pour libérer les messages, puis ajoutez le timeout ou l'acquittement manquant. Les quorum queues les restituent après le timeout consommateur (30 minutes par défaut). |
| Unacked proche de 0, messages toujours en hausse | Chaque consommateur suit le rythme, mais ils ne sont pas assez nombreux, ou le prefetch est trop bas pour les occuper. | Ajoutez des consommateurs et augmentez le prefetch avant de toucher au broker. La documentation situe l'optimum de débit habituel entre 100 et 300. |
| Les consommateurs se déconnectent et se reconnectent sans cesse | Un timeout d'inactivité de load balancer ou de pare-feu plus court que le heartbeat, ou un canal fermé avec PRECONDITION_FAILED par le timeout d'acquittement de livraison. | Réglez le heartbeat en dessous de chaque timeout d'inactivité sur le chemin, et cherchez l'erreur de timeout dans le journal client avant d'augmenter <code>consumer_timeout</code>. |
Une alarme mémoire s'est déclenchée et la publication est bloquée
Confirmez l'alarme et identifiez ce qui occupe la mémoire : la ventilation indique s'il s'agit d'un backlog, d'un problème de connexions ou d'un problème de dimensionnement.
rabbitmq-diagnostics alarms
rabbitmq-diagnostics memory_breakdown --unit "MB"| Si vous constatez | Cela signifie généralement | Que faire |
|---|---|---|
| <code>queue_procs</code> ou la mémoire des quorum queues domine | Un backlog est la cause et l'alarme le symptôme. | Suivez la section 1. L'alarme disparaît quand les files d'attente se vident. |
| <code>connection_*</code> ou <code>binary</code> domine | De nombreuses connexions, des messages volumineux ou un client qui ouvre une connexion par opération. | Comparez <code>rabbitmqctl list_connections name user</code> à ce que vous attendez et repérez le client qui multiplie les connexions. |
| Rien ne domine et la limite semble basse | Le watermark a été abaissé sous la valeur par défaut de 0.6, ou le nœud est sous-dimensionné pour la charge. | Vérifiez la limite dans <code>rabbitmq-diagnostics status</code>. La documentation recommande 0.4 à 0.7 et au moins 30 % laissés à l'OS ; dépasser 0.7 exige un monitoring de la mémoire en place : redimensionnez donc avant de l'augmenter. |
| La mémoire monte régulièrement sans croissance des files d'attente | Une file d'attente non bornée que personne ne surveille, ou la mémoire du write-ahead log des quorum queues. | Bornez les files d'attente. Sur les nœuds hébergeant des quorum queues, la documentation préconise d'allouer au moins trois fois la taille limite du WAL, soit 512 MiB par défaut. |
Une alarme disque s'est déclenchée
Comparez l'espace libre à la limite configurée, sur le volume qui contient réellement le répertoire de données.
rabbitmq-diagnostics alarms
rabbitmq-diagnostics status | grep -A 2 -B 2 "Node data directory"| Si vous constatez | Cela signifie généralement | Que faire |
|---|---|---|
| Le disque est réellement plein | Un backlog sur des quorum queues ou des streams, qui conservent tout sur disque et ne récupèrent pas forcément tout de suite l'espace des messages consommés. | Videz ou supprimez la plus grosse file d'attente, puis agrandissez le volume. En cas de doute, la documentation conseille de surdimensionner le disque. |
| L'espace libre semble suffisant mais l'alarme persiste | La limite est plus élevée que vous ne le pensez, ou le répertoire de données se trouve sur un autre volume que celui que vous avez vérifié. | Confirmez le chemin du répertoire de données avec la commande ci-dessus avant toute modification. |
Un nœud est injoignable ou le cluster s'est partitionné
Déterminez quel côté détient la majorité avant de toucher à quoi que ce soit : avec Raft, le côté majoritaire continue de fonctionner et le côté minoritaire attend.
rabbitmq-diagnostics cluster_status
rabbitmq-queues quorum_status <queue>
rabbitmq-diagnostics check_if_node_is_quorum_critical| Si vous constatez | Cela signifie généralement | Que faire |
|---|---|---|
| Un nœud absent des nœuds actifs, les autres joignables | Fonctionnement normal. La majorité a élu de nouveaux leaders en quelques secondes ; les livraisons des quorum queues ne sont suspendues que du côté isolé. | Rétablissez le réseau. Le membre qui revient se resynchronise auprès du leader et ne peut pas devenir leader avant d'avoir rattrapé son retard. Ne le réinitialisez pas. |
| Aucun côté ne détient la majorité | Les publications, les acquittements et les modifications de métadonnées ne peuvent pas progresser ; ils attendent une majorité ou expirent. | Ramenez les nœuds plutôt que d'en réinitialiser un. Si la seule issue implique de supprimer les données d'un nœud, arrêtez-vous et escaladez. |
| Le nœud isolé était une VM suspendue ou migrée | Une partition de type suspension/reprise : le nœud ne pense pas avoir été défaillant, ses pairs si. | Traitée comme toute partition à nœud unique ; les suspensions courtes sont gérées. Vérifiez le calendrier de migrations et de snapshots de l'hyperviseur. |
| Des partitions se répètent sur un cluster étendu sur plusieurs régions ou zones | C'est la topologie, pas une panne. Le trafic entre nœuds tolère mal une latence ou une gigue élevées. | Exploitez des clusters distincts reliés par fédération ou Shovel pour le trafic intersites. |
| 4.2 ou antérieure, avec <code>autoheal</code> ou <code>ignore</code> | Les deux côtés ont pu accepter des écritures : il y a donc une divergence à réconcilier. | Conservez le côté majoritaire aux données les plus complètes, redémarrez les nœuds de l'autre côté pour qu'ils rejoignent le cluster, puis passez à <code>pause_minority</code>. |
Un nœud ne démarre pas ou ne rejoint pas le cluster
Lisez le journal avant de redémarrer quoi que ce soit une seconde fois : la cause se trouve presque toujours dans la première erreur.
rabbitmq-diagnostics log_tail -N 200
rabbitmq-diagnostics check_running
rabbitmq-diagnostics cluster_status| Si vous constatez | Cela signifie généralement | Que faire |
|---|---|---|
| Erreurs de cookie ou d'authentification | Le cookie Erlang partagé diffère entre les nœuds, ou entre la CLI et le nœud. | Comparez <code>rabbitmq-diagnostics erlang_cookie_hash</code> sur chaque nœud, puis corrigez le fichier, son propriétaire et ses permissions. |
| Erreurs <code>epmd</code> ou <code>nxdomain</code> | Résolution de noms. Sur Kubernetes, la documentation de l'opérateur met en cause le cache CoreDNS ; nous le voyons aussi sur des clusters IPv6 uniquement où Erlang n'a pas été configuré pour IPv6. | Corrigez le DNS ou la résolution du nom d'hôte du nœud, pas RabbitMQ. Voir la section 9 pour le cas Kubernetes. |
| Le nœud n'est pas sur la même version de RabbitMQ que les autres | Il est désynchronisé en pleine mise à niveau. | Alignez son logiciel sur la version majoritaire et laissez-le rejoindre le cluster. Ne rétrogradez pas le cluster pour vous aligner sur lui : le guide de mise à niveau indique que les rétrogradations ne sont pas prises en charge. |
| Erreurs de descripteurs de fichiers ou <code>emfile</code> | La limite de fichiers ouverts est trop basse. Les connexions, les files d'attente et les fichiers de segments des quorum queues sont tous comptabilisés. | Augmentez la limite du service. La documentation demande au moins 50 000, ou deux fois le nombre de connexions au 95e centile plus le nombre de files d'attente. |
Les clients ne peuvent pas se connecter ou échouent à l'authentification
Déterminez s'il s'agit du listener, de TLS ou des identifiants, dans cet ordre.
rabbitmq-diagnostics listeners
rabbitmq-diagnostics check_port_connectivity
rabbitmq-diagnostics check_certificate_expiration| Si vous constatez | Cela signifie généralement | Que faire |
|---|---|---|
| Échecs sur le port 5671 mentionnant des certificats | Le nom du certificat ne correspond pas au nom d'hôte utilisé par les clients, il a expiré, ou un load balancer termine TLS alors que les clients attendent le certificat du broker. | Testez avec <code>openssl s_client -connect <host>:5671 -servername <host></code> en utilisant le nom employé par le client. |
| TLS de fédération, Shovel ou LDAP en échec après une mise à niveau d'Erlang | Depuis Erlang 26, la vérification du pair côté client TLS est activée par défaut : ces liens échouent donc sans certificat et clé client. | Configurez la paire certificat/clé, ou désactivez sciemment la vérification du pair. |
| L'authentification échoue pour une seule application | Son utilisateur n'a aucune permission sur le vhost qu'il ouvre, même si le mot de passe est correct. | Vérifiez <code>rabbitmqctl list_user_permissions <user></code>, pas seulement le mot de passe. |
| Connexion refusée juste après un redémarrage | Le nœud est encore en cours de démarrage, ou une alarme bloque. | Lancez <code>rabbitmq-diagnostics alarms</code> avant d'incriminer le réseau. |
Des liens de fédération ou Shovel sont tombés
Listez les liens et leur état, et comparez-les à une liste écrite de ce qui devrait exister.
rabbitmqctl federation_status --only-down
rabbitmqctl shovel_status
rabbitmqctl list_parameters -p <vhost>| Si vous constatez | Cela signifie généralement | Que faire |
|---|---|---|
| Tous les liens ont redémarré en même temps | D'après notre expérience, c'est attendu après un changement de composition du cluster, comme l'ajout ou le remplacement d'un nœud. | La seule question est de savoir s'ils sont tous revenus, ce qui suppose une liste de ce qui devrait exister. |
| Un lien refuse de s'établir | Les identifiants, le chemin réseau vers l'amont, ou un vhost amont qui n'existe plus. Ces échecs se situent généralement côté amont et ressemblent à des problèmes côté aval. | Vérifiez l'URI et l'utilisateur amont, testez le chemin et confirmez le vhost. Pour les liens TLS, voir la ligne Erlang 26 de la section 6. |
Des messages sont publiés mais jamais reçus
Vérifiez d'abord que le message est bien routé : un exchange sans binding correspondant supprime par défaut les messages sans erreur.
rabbitmqctl list_exchanges -p <vhost> name type
rabbitmqctl list_bindings -p <vhost>| Si vous constatez | Cela signifie généralement | Que faire |
|---|---|---|
| Aucun binding ne correspond à la clé de routage | Le message n'est pas routable. Avec <code>mandatory</code> à false, la valeur par défaut, il est supprimé sauf si un alternate exchange est défini. | Ajoutez un alternate exchange pour que les messages non routables aboutissent à un endroit visible, et surveillez <code>rabbitmq_global_messages_unroutable_dropped_total</code>. |
| Les bindings semblent corrects mais le mauvais consommateur reçoit les messages | Chevauchement de jokers de topic : deux bindings correspondent et les deux files d'attente reçoivent une copie. | Resserrez les motifs de binding. |
| Des messages apparaissent dans la dead-letter queue (DLQ) | Quelque chose les a rejetés ou fait expirer : TTL, limite de longueur, rejet sans remise en file, ou limite de livraison des quorum queues (20 par défaut depuis la 4.0). | Lisez l'en-tête <code>x-death</code> d'un message dead-lettered ; il indique la raison et la file d'attente. |
Des pods ne démarrent pas ou ne s'arrêtent pas sur Kubernetes
Lisez d'abord les événements du pod : la plupart des causes sont extérieures à RabbitMQ.
kubectl describe pod <pod> -n <namespace>
kubectl logs <pod> -n <namespace>
kubectl describe rmq <cluster> -n <namespace>| Si vous constatez | Cela signifie généralement | Que faire |
|---|---|---|
| <code>ImagePullBackOff</code> | Identifiants du registre. | Le secret doit exister dans le namespace du pod et figurer sous <code>imagePullSecrets</code> dans la spec RabbitmqCluster. |
| Pods bloqués en cours d'arrêt | Le hook preStop de l'opérateur retient un pod critique pour le quorum, généralement à cause d'une quorum queue résiduelle. | Vérifiez d'abord l'état du quorum. Ne forcez la suppression qu'une fois certain que la perte des données de ce membre est acceptable. |
| Les pods redémarrent avec une erreur <code>epmd</code> <code>nxdomain</code> | Les nœuds résolvent les noms d'hôte de leurs pairs au démarrage et le cache DNS est obsolète. | La documentation de l'opérateur suggère de réduire le cache CoreDNS de 30 secondes à 5 à 10. |
| Le conteneur échoue sous une politique non-root imposée | Les paramètres du security context ne correspondent pas à l'image. | Définissez <code>runAsUser</code>, <code>runAsGroup</code> et <code>fsGroup</code> de façon cohérente ; <code>fsGroup</code> détermine si le broker peut écrire sur son volume. |
Dépannage RabbitMQ avec l'interface de gestion, les journaux et les métriques
Les sections ci-dessus partent d'un symptôme. Si aucune n'explique le problème, voici où recueillir des éléments avant de modifier quoi que ce soit. Chaque source répond à une question différente, et aucune ne remplace les deux premières commandes en haut de page.
| Source | À utiliser pour | Comment y accéder |
|---|---|---|
| Interface de gestion RabbitMQ | Visualiser les débits de messages globalement et par file d'attente, exchange ou canal, et confirmer si un backlog grossit ou reste stable. | Activez le plugin avec <code>rabbitmq-plugins enable rabbitmq_management</code> (sans redémarrage), puis ouvrez <code>http://<node-hostname>:15672/</code>. Lancez <code>rabbitmq-plugins list</code> pour vérifier qu'il est actif. N'en faites pas votre source d'alertes : le guide de monitoring précise que le plugin de gestion consomme davantage de mémoire et ne conserve que quelques heures d'historique. |
| Journaux | La première erreur derrière un nœud qui ne démarre pas, une connexion refusée ou une alarme. | <code>rabbitmq-diagnostics -q log_location</code> affiche le chemin. Le niveau par défaut est <code>info</code>. <code>rabbitmqctl set_log_level debug</code> l'augmente sur un nœud en cours d'exécution mais ne survit pas à un redémarrage : pensez à le rétablir ensuite. |
| Événements de connexion client | Distinguer un problème réseau d'un problème d'authentification. | Les nœuds journalisent les principaux événements du cycle de vie des connexions, mais seulement une fois la connexion TCP établie et au moins un octet envoyé par le pair. Si rien n'est journalisé pour un client, sa connexion n'a jamais atteint le nœud : examinez le chemin réseau et le listener sur le port 5672 ou 5671. |
| Capture de paquets | Les cas où les journaux ne montrent rien et où vous devez voir ce qui transite sur le réseau. | Le guide de diagnostic réseau cite <code>tcpdump</code> et Wireshark, qui comprennent tous deux chaque protocole pris en charge par RabbitMQ. Capturez côté nœud et côté client, puis comparez. |
| Métriques Prometheus | Les tendances sur plusieurs jours et une alerte avant le prochain incident. | Collectez les métriques du plugin <code>rabbitmq_prometheus</code> sur le port 15692. Le pack de règles d'alerte contient les règles. |
Quand s'arrêter et escalader
Escaladez lorsque l'étape suivante est destructive et non testée. Trois situations justifient un regard extérieur plutôt qu'une heure de plus de votre côté : aucun côté du cluster n'a la majorité et l'issue implique de supprimer les données d'un nœud ; un nœud ne rejoint pas le cluster après une mise à niveau ; une partition en 4.2 ou antérieure où les deux côtés ont accepté des écritures et où vous devez choisir quelles données conserver. Dans les trois cas, l'improvisation aggrave la situation.
Avec un contrat de support AceMQ, un ingénieur senior prend en charge un P1 avec des objectifs de réponse à partir de 15 minutes, selon le plan, 24/7. Sans contrat, le service de diagnostic et de résolution lance une mission d'urgence, et si la cause s'avère être l'application consommatrice plutôt que le broker, nous vous le dirons aussi.
Questions fréquentes
Pourquoi ma file d'attente RabbitMQ ne se vide-t-elle pas ?
Vérifiez d'abord le nombre de consommateurs sur cette file d'attente. Zéro consommateur signifie que rien ne consomme et que le problème se situe dans l'application consommatrice. Des consommateurs présents avec un nombre de messages non acquittés élevé et figé signifie qu'ils détiennent des messages qu'ils n'acquittent jamais, généralement bloqués sur un appel aval sans timeout. Un nombre de messages non acquittés proche de zéro avec une file qui grossit signifie qu'il n'y a pas assez de consommateurs ou que le prefetch est trop bas.
Qu'est-ce qui déclenche une alarme mémoire RabbitMQ ?
Lancez rabbitmq-diagnostics memory_breakdown. Si la mémoire des files d'attente domine, un backlog est en cause et l'alarme disparaît quand il se résorbe. Si la mémoire des connexions ou binary domine, cherchez un excès de connexions ou des messages volumineux. Si rien ne domine, vérifiez le watermark : la valeur par défaut est 0.6 de la mémoire disponible, et la documentation recommande de rester entre 0.4 et 0.7.
Que faire face à une partition réseau RabbitMQ en 4.x ?
À partir de la 4.3, il n'y a plus de stratégie de gestion des partitions à choisir : Khepri, les quorum queues et les streams utilisent tous Raft, donc le côté majoritaire continue de fonctionner et le côté minoritaire attend. Identifiez la majorité avec rabbitmq-diagnostics cluster_status, rétablissez le réseau et laissez les nœuds qui reviennent se resynchroniser. Ne réinitialisez pas de nœuds pour accélérer le processus.
Pourquoi des messages publiés dans RabbitMQ ne sont-ils jamais livrés ?
Généralement parce qu'aucun binding ne correspond à la clé de routage : le message n'est pas routable et il est supprimé silencieusement, sauf si l'éditeur définit mandatory ou si l'exchange dispose d'un alternate exchange. Vérifiez les bindings avec rabbitmqctl list_bindings et ajoutez un alternate exchange pour rendre visibles les messages non routables.
Où se trouvent les journaux RabbitMQ et comment obtenir plus de détails ?
Lancez rabbitmq-diagnostics -q log_location sur le nœud pour afficher le chemin ; l'interface de gestion l'indique aussi sur la page du nœud. Le niveau de journalisation par défaut est info. Pour obtenir une sortie debug sur un nœud en cours d'exécution, utilisez rabbitmqctl set_log_level debug, en gardant à l'esprit que ce changement est temporaire et perdu au redémarrage.
Comment diagnostiquer les problèmes de connexion client RabbitMQ ?
Lancez rabbitmq-diagnostics listeners pour confirmer que le port est ouvert, puis lisez le journal du nœud : il enregistre les événements du cycle de vie des connexions client, mais uniquement pour celles qui ont achevé une négociation TCP et envoyé des données. Aucune entrée signifie que la connexion n'a jamais atteint le nœud : vérifiez le réseau. Un échec d'authentification journalisé désigne plutôt l'utilisateur, le mot de passe ou les permissions sur le vhost. Si les journaux restent muets, capturez le trafic avec tcpdump ou Wireshark.