BlogRabbitMQ

Dépannage RabbitMQ : 12 problèmes de production et comment les résoudre

Scott Sternloff

Par Scott Sternloff, Architecte d’entreprise senior

LinkedIn · Mis à jour le · Lecture : 23 min

Dépannage RabbitMQ : 12 problèmes de production et comment les résoudre
Sur cette page

Cluster tombé, split brain ou disque plein en ce moment même ? Appelez le +1 305-204-2607. Dans le cadre d'un contrat de support, un ingénieur senior AceMQ prend en charge un incident P1 avec des objectifs de réponse à partir de 15 minutes, selon le plan, 24/7. C'est notre support RabbitMQ d'urgence ; le guide ci-dessous sert à comprendre ce qui s'est passé.

La plupart des problèmes RabbitMQ en production se ramènent à une courte liste : une alarme mémoire ou une alarme disque qui bloque les producteurs, une partition de cluster qui a fait perdre sa majorité à une quorum queue, un échec TLS ou d'authentification sur le chemin de connexion, des consommateurs qui n'acquittent plus les messages, ou un bug propre à une version introduit lors d'une mise à niveau. Les vérifier dans cet ordre (état du service, alarmes, état du cluster, connexions, consommateurs) permet de résoudre la plupart des incidents avant d'avoir besoin d'une analyse plus poussée.

Voici les douze problèmes RabbitMQ que nous rencontrons le plus souvent sur les clusters d'entreprise, chacun accompagné de la commande de diagnostic qui le confirme. Plusieurs sont tirés de missions en production menées par nos ingénieurs cette année.

Les problèmes RabbitMQ les plus courants, dans l'ordre où ils surviennent

Avant d'ouvrir le moindre fichier de log, répondez à trois questions, dans cet ordre :

  1. Le broker tourne-t-il ? Un processus rabbitmq-server arrêté ou un nœud planté ressemble, côté client, à s'y méprendre à un problème réseau.
  2. Une alarme est-elle active ? Quand une alarme mémoire ou disque se déclenche, RabbitMQ bloque délibérément les connexions de publication. Le broker est sain : il se protège.
  3. Tous les nœuds sont-ils d'accord sur la composition du cluster ? Une partition où chaque côté croit l'autre disparu est le problème RabbitMQ le plus dommageable, car les écritures peuvent continuer des deux côtés.
rabbitmq-diagnostics check_running     # is the node up and the app started?
rabbitmq-diagnostics alarms            # memory / disk alarms
rabbitmqctl cluster_status             # membership, partitions, running nodes

Lancer ces trois commandes en premier évite l'erreur de dépannage la plus courante : redémarrer un nœud qui allait bien et détruire les indices.

Un mot sur la détection. Si vous apprenez une panne par l'appel d'un client, le problème n'est pas RabbitMQ, c'est l'observabilité. Réglez ce point avant d'optimiser quoi que ce soit d'autre.

1. Split-brain et partitions de cluster

Problème. Les nœuds perdent la connectivité entre eux et chaque côté se croit légitime, ce qui provoque une divergence des données et parfois une perte de messages. C'est particulièrement dangereux dans les déploiements multisites et cloud.

Solution. Les quorum queues s'appuient sur le protocole de consensus Raft et ont besoin qu'une majorité de leurs membres soient disponibles pour élire un leader et accepter les écritures. Un cluster de trois nœuds tolère la perte d'un nœud ; s'il en perd deux, la file cesse d'accepter les écritures, par conception. Ce comportement est correct : forcer le redémarrage d'un nœud pour « réparer » la situation, c'est précisément ainsi que des équipes perdent des messages.

cluster_partition_handling = pause_minority

pause_minority est le réglage sûr par défaut pour les déploiements d'entreprise : le côté minoritaire se met en pause au lieu d'accepter des écritures qu'il ne pourra pas réconcilier. autoheal privilégie la haute disponibilité au détriment de la cohérence, et ignore ne doit être utilisé que si vous gérez vous-même la réconciliation. À partir de RabbitMQ 4.3, ce réglage ne s'applique plus : la 4.3.0 a supprimé Mnesia et, avec lui, les stratégies de gestion des partitions. cluster_partition_handling est toujours accepté dans rabbitmq.conf mais n'a plus aucun effet, et le magasin de métadonnées, les quorum queues et les streams reposent tous sur Raft : seule la règle de majorité Raft détermine quel côté continue à servir. Supprimez cette clé lors de la mise à niveau.

Détecter une partition et y survivre à partir de la 4.3. Les nœuds qui se perdent de vue journalisent la déconnexion, puis les élections de leader Raft qui suivent. rabbitmq-diagnostics cluster_status liste les pairs joignables sous running nodes : un nœud injoignable en est donc simplement absent. rabbitmq-queues quorum_status <queue> indique où se trouvent le leader et les followers de chaque quorum queue, et rabbitmq-diagnostics check_if_node_is_quorum_critical vous dit si l'arrêt d'un nœud laisserait une file ou un stream sans majorité en ligne. La disponibilité dépend du nombre de nœuds : trois nœuds tolèrent une panne, cinq en tolèrent deux, et un nombre pair (quatre, six) ne survit à une partition que si l'un des côtés conserve la majorité. Une partition n'exige pas non plus de panne réseau : un hyperviseur qui suspend une VM, comme lors de certaines migrations à chaud, ressemble à une partition pour le reste du cluster. Les partitions représentaient deux des huit tickets RabbitMQ ouverts dans notre file de support la dernière semaine de septembre 2026.

Deux schémas que nous rencontrons régulièrement sur le terrain :

Maintenance de nœuds Kubernetes sans drain RabbitMQ. Lors d'un audit de cluster en 2026, nous avons relié des pertes de quorum récurrentes à des maintenances de nœuds effectuées sans drainer RabbitMQ au préalable. Un drain Kubernetes évince le pod, mais le nœud RabbitMQ a besoin de son propre arrêt propre pour que les membres des quorum queues puissent transférer leur leadership. Sauter cette étape transforme un simple patch de routine en partition. Le même enchaînement s'applique lorsque vous migrez RabbitMQ 3.x vers 4.x sans interruption de service.

Défauts de quorum propres à une version. Sur la même mission, nous avons isolé des erreurs de reconnaissance de nœuds dues à un défaut de la version 4.2.3, corrigé dans les builds 4.2.x ultérieurs et dans la série 4.3. Si les erreurs de composition persistent après un redémarrage propre et avec une configuration correcte, consultez les release notes de votre version de correctif exacte avant de tout repenser.

Pour les clusters de reprise après sinistre, vérifiez que le site de secours s'active uniquement en cas de panne du site principal. Un cluster de secours qui démarre alors que le site principal est sain est une machine à split-brain ; la reprise exige alors de recréer manuellement les nœuds et de relancer les élections, et non une simple bascule automatique.

2. Alarmes mémoire et disque qui bloquent les producteurs

Problème. Les producteurs restent bloqués pendant que les consommateurs continuent de vider les files. Rien ne semble anormal dans les logs.

Solution. RabbitMQ bloque les connexions de publication lorsque l'utilisation mémoire franchit le seuil haut (40 % de la RAM disponible par défaut) ou que l'espace disque libre passe sous la limite configurée (50 Mo par défaut).

rabbitmq-diagnostics alarms
rabbitmq-diagnostics memory_breakdown

La répartition compte davantage que le total. Une mémoire occupée par le contenu des files signifie que les messages ne sont pas consommés assez vite : c'est un problème de consommateurs déguisé en problème de mémoire. Une mémoire occupée par l'état des connexions et des canaux clients indique généralement qu'une application en laisse fuir, souvent parce qu'elle ouvre un canal par message au lieu d'en réutiliser un.

Relever vm_memory_high_watermark est un pis-aller, pas un correctif. Commencez par comprendre pourquoi la mémoire est occupée : une limite plus haute face à un vrai backlog ne fait que retarder la même panne. Les alarmes se lèvent automatiquement dès que l'utilisation repasse sous le seuil.

3. Backlog de messages et contrôle de flux

Problème. Les files s'allongent ou l'utilisation disque atteint une limite, RabbitMQ active le contrôle de flux et les producteurs ralentissent ou se bloquent, ce qui perturbe les pipelines en amont et provoque des timeouts.

Solution. Concevez pour des files courtes. Ajoutez des consommateurs pour traiter les messages plus vite, et configurez les limites de segments des quorum queues en fonction de vos besoins de rétention. Réglez délibérément les seuils mémoire et disque plutôt que de garder les valeurs par défaut sur un hôte de grande taille, et alertez sur la tendance de la profondeur des files plutôt que sur sa valeur absolue : une file qui grossit régulièrement pendant dix minutes est un meilleur signal qu'un pic bref.

4. Messages non acquittés et consommateurs bloqués

Problème. Les consommateurs reçoivent les messages mais ne les acquittent jamais. Les messages non acquittés s'accumulent, la mémoire grimpe et la file se bloque.

Solution. Identifiez lequel des trois cas de figure vous concerne :

rabbitmqctl list_queues name messages messages_unacknowledged consumers
  • Beaucoup de messages, zéro consommateur : l'application consommatrice est arrêtée, ou son abonnement pointe vers la mauvaise file ou le mauvais virtual host.
  • Beaucoup de messages, des consommateurs présents, beaucoup de non-acquittés : les consommateurs reçoivent mais n'envoient jamais l'ack. Le plus souvent, un client qui plante en cours de traitement, ou qui oublie l'ack sur un chemin d'exception. Définissez un consumer_timeout pour que les livraisons bloquées soient remises en file au lieu d'être retenues indéfiniment.
  • Beaucoup de messages, quasiment aucun non-acquitté : les consommateurs ne suivent pas. Ajoutez des instances, ou revoyez le prefetch.

Le prefetch est l'erreur de configuration la plus courante. Un prefetch illimité permet à un consommateur de s'approprier des milliers de messages pendant que les autres restent inactifs ; un prefetch de 1 ajoute un aller-retour réseau par message. Nous détaillons ce compromis dans régler le prefetch count de RabbitMQ, et la même logique s'applique à toute topologie pub/sub qui distribue les messages sur plusieurs files.

La métrique consumer capacity de l'interface de gestion RabbitMQ est ici la lecture la plus rapide. Une consumer capacity durablement faible avec une file profonde signifie que le goulot d'étranglement se situe en aval de RabbitMQ, et non dans le broker.

5. Un type de file inadapté à la charge

Problème. Les files classiques peinent dans les environnements à fort churn et avec des backlogs importants, et deviennent instables sous forte charge.

Solution. Utilisez les quorum queues pour la durabilité en entreprise. Elles offrent un comportement prévisible sous charge et une bien meilleure reprise en cas de bascule. Vérifiez que vos clients prennent en charge les publisher confirms pour la sécurité des données et, si l'ordre strict compte, validez explicitement le comportement des consommateurs : les quorum queues modifient la sémantique de redélivraison d'une façon que certaines applications remarquent. Consultez migrer des files classiques vers les quorum queues pour la démarche de migration.

6. Files en miroir obsolètes et politiques HA mal configurées

Problème. Les files classiques en miroir, désormais obsolètes, basculent de façon incohérente, ce qui provoque des retards de synchronisation et un risque de perte de données. Des politiques de mise en miroir trop larges consomment des ressources et réduisent le débit.

Solution. Migrez vers les quorum queues pour une haute disponibilité moderne. Évitez les politiques de mise en miroir globales ; définissez explicitement le comportement HA et testez la bascule à intervalles réguliers plutôt que de la découvrir en plein incident. Si vous exploitez encore des files en miroir, surveillez le retard de synchronisation et vérifiez que la topologie des miroirs correspond à l'intention : un motif de politique qui correspond par erreur à toutes les files est une cause fréquente de pression inexpliquée sur les ressources.

7. TLS, certificats et échecs de connexion

Problème. Les clients n'arrivent pas à se connecter, ou se connectent et sont immédiatement rejetés.

Solution. Séparez le diagnostic en deux. Aucune connexion possible : vérifiez que le listener écoute sur le port attendu. RabbitMQ utilise le port 5672 pour l'AMQP en clair et le 5671 pour l'AMQP sur TLS. Les déploiements durcis désactivent complètement le 5672, un changement qui casse tous les clients encore configurés sur l'ancien port. Capturez le trafic TCP avec tcpdump et analysez-le dans Wireshark pour prouver où la connexion meurt.

Connexion établie puis échec : vérifiez les permissions et le virtual host. Des identifiants valides sans permission sur le virtual host cible s'authentifient correctement, puis échouent sur chaque opération.

rabbitmqctl list_users
rabbitmqctl list_permissions -p /your-vhost

Avec les backends OAuth 2.0 et LDAP, activez la journalisation des décisions avant de conclure à de mauvais identifiants : les échecs de contrôle d'accès viennent souvent d'un scope OAuth ou d'un filtre de recherche mal configuré plutôt que d'un mauvais mot de passe.

Les échecs de handshake TLS méritent une attention particulière. Lors d'une récente mission de support, la messagerie sécurisée échouait sur le port 5671 alors que les certificats PEM étaient correctement installés sur chaque nœud. Le handshake se terminait au niveau du load balancer. La cause : un certificat qui ne correspondait pas. Le common name et les champs SAN doivent correspondre au nom d'hôte auquel le client se connecte réellement, c'est-à-dire, pour un cluster derrière un load balancer, l'adresse du load balancer et non le nom d'hôte de chaque nœud. Lorsque le TLS mutuel n'est pas une exigence ferme, supprimer l'obligation de certificat client élimine toute une catégorie de ces échecs.

Deux détails opérationnels à documenter dès maintenant plutôt qu'à découvrir plus tard : un certificat d'AC personnalisé doit être installé sur chaque poste client, y compris les clients Windows, qui ne le récupèrent pas automatiquement ; et les certificats d'AC émis pour une durée de 10 ans nécessitent malgré tout une procédure de rotation documentée. Un certificat qui expire sans responsable désigné, c'est une panne programmée.

Vous êtes face à un problème de cluster RabbitMQ impossible à isoler ? Les ingénieurs AceMQ interviennent chaque jour sur des clusters en production, y compris pour la récupération de quorum queues et l'analyse forensique de partitions. Parlez à un ingénieur AceMQ : en général, une seule session nous suffit pour vous dire s'il s'agit de configuration, d'infrastructure ou d'un défaut connu.

Problème. rabbitmqctl n'arrive pas à joindre le nœud, et le serveur RabbitMQ semble arrêté alors qu'il fonctionne parfaitement.

Solution. Trois causes expliquent la quasi-totalité de ces cas :

  • Cookie Erlang différent. Chaque nœud et chaque outil CLI doivent partager la même valeur de cookie (/var/lib/rabbitmq/.erlang.cookie sur la plupart des déploiements Linux, ou le répertoire du profil utilisateur depuis une invite de commandes Windows). Un cookie Erlang différent produit des erreurs d'authentification qui imitent un broker mort. Sous Windows, le cas typique est un service qui tourne sous SYSTEM alors que la CLI s'exécute en tant qu'Administrateur : il faut copier le cookie d'un profil à l'autre et corriger ses permissions.
  • Résolution du nom d'hôte. Les nœuds sont identifiés sous la forme rabbit@hostname. Si le nom d'hôte change, ce qui est fréquent après la reconstruction d'un conteneur ou d'une VM, le nœud ne peut plus rejoindre son propre cluster RabbitMQ.
  • Ports inter-nœuds bloqués. En plus de l'AMQP sur le 5672, un cluster a besoin des ports 4369 (epmd) et 25672 pour le trafic TCP entre nœuds. Des règles de pare-feu qui n'ouvrent que le port client cassent le clustering sans bruit.

Pour redémarrer proprement un nœud plutôt que de tuer le processus :

rabbitmqctl stop_app && rabbitmqctl start_app

Cela arrête l'application RabbitMQ en laissant tourner la VM Erlang, ce qui préserve bien plus d'informations de diagnostic qu'un redémarrage complet du service RabbitMQ.

9. Analyse antivirus et contention des E/S disque

Problème. La base Mnesia et les fichiers de files de RabbitMQ sont analysés par l'antivirus du poste ou par un outil de sécurité en temps réel, en particulier sur les serveurs Windows d'entreprise. Résultat : une forte dégradation des performances et des ralentissements de nœuds inexpliqués, qui ressemblent à un défaut de RabbitMQ.

Solution. Ajoutez les répertoires de données de RabbitMQ à la liste d'exclusions de votre antivirus ou de votre solution de protection des terminaux. Vous évitez ainsi les E/S intensives et les verrous de fichiers qui peuvent mettre un nœud à genoux. Confirmez les chemins exacts de votre déploiement avec rabbitmq-diagnostics status, qui indique le répertoire de données configuré. Ce problème passe facilement inaperçu, car rien dans les fichiers de logs de RabbitMQ ne le signale.

10. Contention des ressources sur les machines virtuelles

Problème. Les nœuds qui tournent dans des VM partagent CPU, RAM et E/S disque avec d'autres charges, ce qui entraîne une latence imprévisible, des files bloquées, voire de véritables pannes de nœuds.

Solution. Dédiez des cœurs CPU à RabbitMQ et réservez de la mémoire pour chaque VM qui héberge un nœud. Surveillez le CPU steal time, la latence disque et la pression mémoire dans Grafana, à côté de vos métriques RabbitMQ : le steal time, en particulier, est invisible depuis le broker et explique une bonne partie des signalements « RabbitMQ est lent » qui n'ont rien à voir avec RabbitMQ. Évitez les hyperviseurs surchargés et le stockage partagé pour les nœuds de production.

11. Réglage des heartbeats et des timeouts réseau

Problème. Dans les déploiements à forte latence, cloud ou WAN, les heartbeats et timeouts TCP par défaut provoquent de fausses détections de panne de nœud et des partitions réseau inutiles.

Solution. Allongez les intervalles de heartbeat et ajustez tcp_listen_options à votre environnement plutôt que de conserver des valeurs par défaut pensées pour un LAN à faible latence. Réglez les paramètres de distribution Erlang pour fiabiliser les échanges entre nœuds. Un cluster réparti sur plusieurs zones de disponibilité a besoin de timeouts différents de ceux d'un cluster logé dans une seule baie, et des réglages inadaptés se traduisent ici par des partitions sans aucune panne réseau sous-jacente.

12. Échecs de mise à niveau et de plugins

Problème. Le broker refuse de démarrer après une mise à niveau, avec une erreur qui n'indique pas la vraie cause.

Solution. Deux risques distincts. Chaque série de versions de RabbitMQ exige une plage de versions Erlang/OTP prise en charge ; une mise à niveau sur un build Erlang non supporté produit des échecs de démarrage qui ressemblent à des problèmes de configuration. Consultez la matrice de compatibilité avant la fenêtre de maintenance, pas pendant.

Les plugins sont la seconde cause. Un plugin compilé pour une version antérieure du broker peut refuser de se charger après une mise à niveau. Désactivez les plugins tiers, vérifiez que le nœud démarre, puis réactivez-les un par un.

Enfin, suivez les avis de sécurité de votre série. Le projet RabbitMQ publie régulièrement des notifications de CVE et des versions correctives ; exploiter un déploiement open source sans personne chargé de surveiller ces avis, c'est découvrir les vulnérabilités par la bouche d'un auditeur. Si vous comparez cette charge opérationnelle à un abonnement commercial, nous détaillons les options dans licences RabbitMQ et support commercial.

Quatre modes de défaillance tirés de missions récentes en production

Les douze problèmes ci-dessus couvrent ce que l'on observe le plus souvent sur les clusters d'entreprise. Quatre modes de défaillance précis méritent un examen plus attentif, car chacun est mal diagnostiqué de la même façon, encore et encore : l'équipe traite un comportement voulu comme un bug, ou un signal passager comme un non-événement, et perd du temps à chercher le mauvais correctif.

Perte de quorum quand un nœud Kubernetes est drainé sans arrêt propre

Un drain Kubernetes évince le pod. Il ne demande pas, à lui seul, au nœud RabbitMQ qui tourne dans ce pod de transférer le leadership des quorum queues dont il est actuellement leader. Si le processus est simplement tué à l'expiration du délai de grâce, toutes les quorum queues pilotées depuis ce nœud perdent leur leader d'un coup, et le cluster doit organiser une élection complète en pleine charge au lieu d'un transfert propre.

La solution : un hook PreStop qui appelle rabbitmqctl stop_app avant que Kubernetes ne termine l'éviction du pod :

lifecycle:
  preStop:
    exec:
      command: ["rabbitmqctl", "stop_app"]
terminationGracePeriodSeconds: 60

stop_app arrête proprement l'application RabbitMQ tant que le nœud est encore joignable, de sorte que les leaders de quorum queues de ce nœud transfèrent leur rôle avant l'arrêt effectif du pod. Prévoyez un terminationGracePeriodSeconds suffisant pour que l'opération se termine, et vérifiez que le transfert a bien eu lieu avant de faire confiance à l'automatisation : rabbitmqctl list_queues name type leader online_members ne doit plus montrer aucune file pointant vers le nœud que vous venez de drainer. Le même enchaînement s'applique à un redémarrage manuel au niveau de l'OS, pas seulement à Kubernetes : arrêtez d'abord l'application, puis le processus.

Un défaut de reconnaissance de nœuds lié à une version précise

Si un nœud rejoint un cluster et continue de renvoyer des erreurs de composition qu'un redémarrage propre et une configuration vérifiée ne résolvent pas, ne présumez pas que le problème vient de votre topologie. RabbitMQ a déjà livré des défauts propres à certaines versions dans ce domaine, dont un qui affectait la reconnaissance des nœuds dans la version 4.2.3 et qui a été corrigé dans les builds 4.2.x ultérieurs et dans la série 4.3. Avant de repenser le réseau ou la découverte des pairs pour contourner un symptôme, consultez les release notes et le changelog de votre version de correctif exacte. Récupérez rabbitmqctl cluster_status sur chaque nœud, et pas seulement sur celui qui se plaint, puis comparez les chaînes de version RabbitMQ et Erlang/OTP sur l'ensemble du cluster : une version de correctif différente sur un nœud est un signe avant-coureur fréquent de ce type d'erreur.

Des alarmes mémoire qui se déclenchent en pic et se lèvent avant que vous puissiez regarder

Une alarme mémoire qui se déclenche pendant un pic de trafic et se lève d'elle-même cinq minutes plus tard ne laisse aucune trace au moment où quelqu'un ouvre l'interface de gestion. L'alarme a fait son travail, mais vous ne savez toujours pas pourquoi elle s'est déclenchée, et elle se déclenchera de nouveau au prochain pic. Trois sources permettent de la retrouver après coup. Exécutez rabbitmq-diagnostics memory_breakdown à intervalle court pendant les périodes de pic connues, et pas seulement quand quelqu'un remarque un problème : vous disposerez ainsi d'une répartition prise au moment qui compte, et non d'une moyenne calculée sur une période calme. Recherchez dans le log RabbitMQ les entrées alarm_handler et vm_memory_high_watermark : chaque changement d'état d'alarme est journalisé avec un horodatage, même une fois l'alarme levée. Enfin, si vous utilisez Prometheus, alertez lorsque rabbitmq_alarms_memory_used_watermark et rabbitmq_alarms_file_descriptor_limit passent à une valeur non nulle sur une fenêtre donnée, et pas seulement sur la valeur du dernier scrape : un pic de cinq minutes entre deux scrapes espacés de 30 secondes reste visible dans l'historique de la métrique, même si la vue courante du tableau de bord semble propre.

Une reprise après partition menée selon un plan, pas improvisée

pause_minority fait son travail automatiquement : le côté qui ne voit pas de majorité se met en pause au lieu d'accepter des écritures qu'il ne pourra pas réconcilier. L'erreur des équipes, c'est la suite, quand quelqu'un se précipite pour ramener le nœud en pause sans rien vérifier. Avant de laisser un nœud rétabli reprendre du trafic, vérifiez trois choses : que le côté en pause n'a réellement accepté aucune écriture pendant la séparation (c'est attendu avec pause_minority, mais vérifiez-le au lieu de le supposer), que rabbitmqctl cluster_status sur le nœud qui revient montre qu'il se synchronise sur la majorité actuelle et non sur sa propre vue périmée, et que rabbitmq-diagnostics check_running passe sans erreur avant qu'il ne prenne du trafic de production. Formalisez cette procédure dans un runbook, avec un approbateur nommé pour l'étape de réintégration. Une partition gérée par une suite de commandes improvisées sous la pression d'un incident, c'est ainsi qu'un événement récupérable se transforme en chantier de réconciliation manuelle des données.

Les commandes de diagnostic à lancer en premier

Gardez cette liste à côté du runbook d'incident. Chaque commande vous apprend quelque chose de différent, et les exécuter dans un ordre logique avant de toucher à la configuration préserve les indices dont vous aurez besoin si le problème s'avère être un défaut plutôt qu'une erreur de configuration.

rabbitmqctl cluster_status                                    # membership, partitions, which nodes are up
rabbitmq-diagnostics check_running                             # is the app started on this node
rabbitmq-diagnostics alarms                                    # active memory or disk alarms right now
rabbitmq-diagnostics memory_breakdown                           # what's actually holding the memory
rabbitmqctl list_queues name type leader online_members         # queue type, current leader, replica health
rabbitmqctl list_connections name peer_host state                # who's connected and from where
rabbitmqctl list_channels connection prefetch_count messages_unacknowledged  # prefetch and ack backlog per channel
rabbitmq-diagnostics environment                                # effective config, not just the config file
rabbitmq-diagnostics status                                     # version, uptime, data directory, listeners
rabbitmqctl list_permissions -p /your-vhost                      # confirm access isn't the actual problem

Lancez les trois premières avant toute autre chose. Elles vous indiquent, dans cet ordre, si le nœud tourne, s'il se protège délibérément avec une alarme et si le cluster est d'accord sur sa propre composition. Redémarrer un nœud sans avoir vérifié ces trois points est de loin le moyen le plus courant de détruire les indices nécessaires pour trouver la vraie cause.

Si le diagnostic pointe spécifiquement vers Kubernetes, consultez la supervision de RabbitMQ sur Kubernetes pour les métriques sur lesquelles il vaut la peine d'alerter au-delà de celles présentées ici. Si la colonne messages_unacknowledged reste élevée, le prefetch count est la prochaine chose à vérifier. Pour un cluster qui dépasse la topologie pour laquelle il a été conçu, consultez l'architecture RabbitMQ de production pour l'entreprise. Et si l'un des quatre modes de défaillance ci-dessus vous rappelle votre propre cluster, notre service de dépannage RabbitMQ et notre équipe support mènent ce diagnostic tous les jours, avec des objectifs de réponse à partir de 15 minutes, selon le plan, et une ligne directe avec l'équipe principale (core team) de RabbitMQ lorsque la cause s'avère être un défaut et non une erreur de configuration.

Supervision : détecter ces problèmes avant d'être réveillé

La plupart des problèmes RabbitMQ sont visibles dans les métriques bien avant de devenir des pannes.

rabbitmq-plugins enable rabbitmq_management    # management UI on 15672
rabbitmq-plugins enable rabbitmq_prometheus    # metrics on 15692

L'interface de gestion RabbitMQ vous donne l'onglet Queues, des vues sur le cycle de vie des connexions et sur les canaux, ainsi que la répartition de la mémoire par nœud, sans toucher à la CLI. Le plugin de gestion est le moyen le plus rapide de vérifier l'état du broker pendant un incident.

Une configuration pragmatique tirée d'un déploiement récent : un intervalle de scrape de 30 secondes assure une collecte continue sans saturer le stockage, et les métriques par file ont été volontairement laissées désactivées sur un cluster à faible trafic. Sur un broker qui compte des milliers de files, la cardinalité par file produit d'énormes volumes de données que personne ne lit. Les contrôles de santé au niveau des nœuds et du cluster ont détecté chaque incident réel sur ce système.

Surveillez au minimum : l'état des alarmes mémoire et disque, la profondeur des files, la consumer capacity, le nombre de messages non acquittés, la disponibilité des nœuds et les événements de partition. Ces six métriques couvrent tous les modes de défaillance de ce guide.

Pour les fichiers de logs, augmentez le niveau de log temporairement et non de façon permanente : la journalisation debug sur un broker chargé génère assez de volume pour déclencher l'alarme disque que vous êtes en train de diagnostiquer :

rabbitmqctl set_log_level debug
# reproduce the issue, then
rabbitmqctl set_log_level info

Si un nœud a carrément planté, cherchez un fichier de dump erl_crash.dump dans le répertoire de données de RabbitMQ. Le visualiseur de crash dumps Erlang (cdv) montre quel processus est mort et combien de mémoire il occupait : c'est souvent la voie la plus rapide vers la cause racine lorsque le nœud n'a laissé aucune entrée de log utile.

À faire aussi régulièrement : sauvegardez la configuration du cluster et les définitions des utilisateurs, pour que la reprise après sinistre ne tourne pas à l'archéologie ; simulez un trafic réel et des scénarios de panne en préproduction ; et suivez les changements de configuration et de topologie dans votre dépôt d'infrastructure as code, afin de pouvoir relier une régression à un changement.

Quand faire appel au support RabbitMQ

À traiter en interne : redémarrages d'un seul nœud, analyse des alarmes, corrections de permissions et de virtual hosts, réglage du prefetch, conflits de plugins, exclusions antivirus.

Faites appel au support lorsque vous êtes confronté à :

  • Une partition de cluster où les deux côtés ont accepté des écritures et qu'il faut réconcilier
  • Des quorum queues qui restent indisponibles alors que tous les nœuds ont été confirmés sains
  • Des plantages à répétition sans cause claire dans les fichiers de logs ni dans l'analyse des fichiers de dump
  • Une perte de messages que vous ne parvenez pas à expliquer
  • Une mise à niveau sur plusieurs versions majeures d'un cluster que vous ne pouvez pas mettre hors ligne
  • Des avis de sécurité visant une version que vous ne pouvez pas corriger rapidement

Ces situations ont un point commun : le coût d'une fausse manœuvre dépasse celui d'un second avis. Forcer le retour en ligne d'une quorum queue sans savoir quel côté détient les données de référence transforme une partition récupérable en perte de données définitive. Pour une revue écrite de votre cluster, un bilan de santé RabbitMQ couvre ces douze problèmes.

Si le broker que vous dépannez tourne sur une version que le projet open source ne maintient plus (la 3.13 et toutes les précédentes, en 2026), vérifiez si le correctif dont vous avez besoin a seulement été livré pour votre série avant de passer une nuit sur un contournement. Beaucoup des problèmes ci-dessus n'ont été corrigés en amont que dans des versions ultérieures. Vous n'êtes pas obligé de mettre à niveau pour rester protégé : le support étendu des anciennes versions de RabbitMQ rétroporte les correctifs de sécurité sur les brokers 3.x, ce qui vous permet de garder l'ancien cluster en service le temps de planifier correctement la mise à niveau.

Deux compléments à cette liste. Si le symptôme est une lenteur plutôt qu'une panne, suivez le guide d'optimisation des performances de RabbitMQ, qui enchaîne les vérifications dans l'ordre qui permet de trouver le goulot d'étranglement le plus vite. Et si vous voulez savoir à quelle fréquence chacun de ces problèmes survient réellement, notre analyse de 145 tickets de support RabbitMQ les ventile par catégorie et par année.

AceMQ propose du conseil RabbitMQ pour les déploiements d'entreprise : réponse aux incidents 24/7 garantie par SLA, audits de cluster, planification des mises à niveau et application des correctifs de CVE. Que vous exploitiez RabbitMQ open source ou un abonnement commercial, nous pouvons vous aider à résoudre vos problèmes RabbitMQ avant qu'ils ne deviennent des interruptions de service.

FAQ dépannage RabbitMQ

Pourquoi RabbitMQ n'accepte-t-il plus de messages ?

La cause la plus fréquente est une alarme mémoire ou disque active. RabbitMQ bloque les connexions de publication lorsque l'utilisation mémoire dépasse le seuil haut (high watermark, 40 % de la RAM par défaut) ou que l'espace disque libre passe sous la limite configurée (50 Mo par défaut). Lancez rabbitmq-diagnostics alarms pour le confirmer.

Comment savoir si un cluster RabbitMQ est partitionné ?

Lancez rabbitmqctl cluster_status sur chaque nœud. Si les nœuds ne rapportent pas la même composition, ou si une section partitions apparaît dans la sortie, le cluster RabbitMQ est partitionné. Comparez la sortie de tous les nœuds : la vue d'un seul nœud ne suffit pas.

Pourquoi une quorum queue RabbitMQ devient-elle indisponible ?

Les quorum queues ont besoin qu'une majorité de leurs membres soient en ligne pour élire un leader. Une file répartie sur trois nœuds tolère la perte d'un nœud, mais cesse d'accepter les écritures si deux sont indisponibles. Vérifiez d'abord la disponibilité des nœuds, puis assurez-vous qu'aucun défaut propre à votre version de correctif n'est en cause.

Pourquoi mes connexions TLS à RabbitMQ échouent-elles sur le port 5671 ?

En général, à cause d'un certificat dont le common name ou les champs SAN ne correspondent pas au nom d'hôte auquel le client se connecte. Dans un cluster derrière un load balancer, ce doit être l'adresse du load balancer, et non le nom d'hôte de chaque nœud. Sinon, même des certificats valides font échouer le handshake.

Comment récupérer des messages bloqués dans une file RabbitMQ ?

Déterminez si les consommateurs sont absents, s'ils n'envoient pas d'ack ou s'ils sont trop lents, avec rabbitmqctl list_queues name messages messages_unacknowledged consumers. Les messages non acquittés reviennent automatiquement dans la file à la fermeture de la connexion client : ils ne sont pas perdus.

Pourquoi RabbitMQ est-il lent alors que les logs ne montrent aucune erreur ?

Cherchez en dehors du broker. L'analyse antivirus des répertoires Mnesia et des files, le CPU steal time sur un hyperviseur partagé et la contention des E/S disque dégradent fortement RabbitMQ sans produire la moindre entrée dans ses logs.

Où se trouvent les fichiers de logs de RabbitMQ ?

En général dans /var/log/rabbitmq/ sous Linux et dans le répertoire de données de RabbitMQ sous Windows. Confirmez le chemin exact avec rabbitmq-diagnostics status, qui indique l'emplacement configuré des fichiers de logs.

Peut-on faire tourner RabbitMQ 3.x en production en toute sécurité ?

Oui, mais seulement avec une filière de correctifs. Les nouveaux développements et les correctifs de sécurité visent la série 4.x : un cluster 3.x non supporté accumule donc, avec le temps, des vulnérabilités publiées et non corrigées. Si vous ne pouvez pas migrer au rythme qu'impose le calendrier de versions de la communauté, un support étendu au-delà de la 3.12.x continue de fournir correctifs, améliorations de performances et mises à jour de sécurité pour les anciennes versions, ce qui fait généralement toute la différence entre exploiter la 3.x en sécurité et vivre en sursis.

Pourquoi mon cluster RabbitMQ perd-il le quorum pendant une maintenance Kubernetes ?

Un drain Kubernetes évince le pod, mais ne demande pas d'abord à RabbitMQ de transférer le leadership des quorum queues. Si le nœud est tué à l'expiration du délai de grâce, toutes les files dont il était leader perdent leur leader en même temps et le cluster doit en élire de nouveaux en pleine charge. Ajoutez un hook PreStop qui exécute `rabbitmqctl stop_app` avant l'arrêt du pod, et prévoyez un `terminationGracePeriodSeconds` suffisant pour terminer le transfert. Avant de considérer le drain comme sûr, vérifiez avec `rabbitmqctl list_queues name type leader online_members` qu'aucune file ne pointe encore vers le nœud drainé.

Quelle commande lancer en premier quand RabbitMQ se comporte mal ?

Lancez `rabbitmq-diagnostics check_running` pour confirmer que l'application est bien démarrée, `rabbitmq-diagnostics alarms` pour voir si RabbitMQ bloque volontairement les producteurs, et `rabbitmqctl cluster_status` pour vérifier que tous les nœuds sont d'accord sur la composition du cluster. Exécutez les trois avant de redémarrer quoi que ce soit. La plupart des incidents se résolvent dès que l'on sait dans lequel de ces trois états on se trouve réellement, alors qu'un redémarrage précipité détruit les indices qui auraient permis d'identifier la vraie cause.

Les dix schémas à l'origine de la plupart de ces problèmes, chacun avec son symptôme, sa cause racine et son correctif, sont présentés dans l'ordre dans le guide de fiabilité RabbitMQ.

Scott Sternloff

Auteur

Scott SternloffArchitecte d’entreprise senior

Architecte d’entreprise senior chez AceMQ. Il signe ici les contenus techniques : architecture RabbitMQ, Kafka et Redis, clustering et migrations.

Consultation gratuite

Un regard expert sur votre cluster RabbitMQ

Que vous deviez résoudre un incident de production, planifier une migration ou obtenir un second avis sur votre architecture, notre équipe est prête. Pas d’argumentaire commercial, seulement des réponses.

Nous écrire