A RabbitMQ health check answers one question: can this node accept work right now? The answer you need depends on who is asking. Docker Compose wants to know when to start your app, a load balancer wants to know where to send connections, and your on-call engineer wants to know why messages pile up. This guide gives you a ready-to-use check for each case.
This is the snippet most people are looking for. It waits until the node responds and has no resource alarm, then starts the app:
services:
rabbitmq:
image: rabbitmq:4-management
ports:
- "5672:5672"
- "15672:15672"
healthcheck:
test: ["CMD", "rabbitmq-diagnostics", "-q", "check_running"]
interval: 10s
timeout: 10s
start_period: 30s
retries: 5
app:
build: .
depends_on:
rabbitmq:
condition: service_healthycheck_running fails until the RabbitMQ application is fully booted on the node, which is exactly what your app needs before it opens a connection. If you only want "is the process alive", use ping, described below.
The official monitoring guide describes health checks as stages. Each stage checks more than the one before, and costs a bit more.
| Stage | Command | What it checks | Good for |
|---|---|---|---|
| 1 | rabbitmq-diagnostics -q ping | The Erlang VM is up and the node answers CLI tools | Liveness, "is the process alive" |
| 2 | rabbitmq-diagnostics -q status | Stage 1, plus the node can report its status | Basic sanity checks |
| 3 | rabbitmq-diagnostics -q check_running and check_local_alarms | RabbitMQ is running and no memory or disk alarm is blocking publishers | Readiness, Docker Compose |
| 4 | rabbitmq-diagnostics -q check_port_connectivity | Every listener (AMQP, management, Prometheus…) accepts TCP connections | Load balancers, smoke tests |
| 5 | rabbitmq-diagnostics -q check_virtual_hosts | Every virtual host is running on the node | Post-upgrade and post-restart checks |
Every command exits with code 0 on success and non-zero on failure, so they plug directly into any probe, script or CI step. The -q flag removes the informational banner.
It is tempting to make the health check as thorough as possible. That backfires for liveness checks. If a node has a memory alarm, it is still alive and will recover once consumers catch up. A liveness probe that fails on alarms makes your orchestrator restart a node that was about to heal, and the restart drops every connection on it. Keep liveness shallow (stage 1 or 2) and use deeper checks for readiness and alerting.
node_health_checkYou may find rabbitmq-diagnostics node_health_check in older blog posts and Helm charts. The RabbitMQ docs say not to use it: it has been deprecated for a long time and is a no-op in modern versions. Replace it with the stage 3 commands above.
rabbitmq-diagnostics -q pingThe cheapest check. It succeeds as soon as the Erlang runtime is up and reachable by CLI tools, even if RabbitMQ itself is still booting.
rabbitmq-diagnostics -q check_running && rabbitmq-diagnostics -q check_local_alarmsThis pair is the stage 3 check recommended by the docs. check_running fails while the node is booting or has been stopped with rabbitmqctl stop_app. check_local_alarms fails when the node has a memory or free disk alarm, which is the moment RabbitMQ starts blocking publishers. To see the alarms without failing, use rabbitmq-diagnostics -q alarms.
rabbitmq-diagnostics -q check_port_connectivityOpens a TCP connection to every listener the node has. It doesn't do a protocol handshake or authenticate, so it proves the port is open, not that your user can log in. To see the list of listeners first:
rabbitmq-diagnostics -q listenersrabbitmq-diagnostics -q check_virtual_hostsFails if any virtual host is down on the node. A vhost can fail on its own (for example after a corrupted message store) while the node stays up, so this check catches problems the others miss.
rabbitmq-diagnostics -q check_if_node_is_quorum_criticalNot a health check for probes, but useful in maintenance scripts. It fails if stopping this node would make a quorum queue or stream lose its majority. Run it before restarting or upgrading a node in a cluster.
If the management plugin is enabled, the same checks are available over HTTP on port 15672. They are handy when your load balancer or monitoring tool can only make HTTP calls. They need a user with at least the monitoring tag.
# Resource alarms in the whole cluster
curl -u monitor:secret http://localhost:15672/api/health/checks/alarms
# Resource alarms on the node that serves the request
curl -u monitor:secret http://localhost:15672/api/health/checks/local-alarms
# A listener is up on a given port
curl -u monitor:secret http://localhost:15672/api/health/checks/port-listener/5672
# A listener is up for a given protocol (amqp091, amqp10, mqtt, stomp…)
curl -u monitor:secret http://localhost:15672/api/health/checks/protocol-listener/amqp091
# All virtual hosts are running
curl -u monitor:secret http://localhost:15672/api/health/checks/virtual-hosts
# Stopping this node would not break a quorum queue
curl -u monitor:secret http://localhost:15672/api/health/checks/node-is-quorum-critical
# A TLS certificate expires within 4 weeks
curl -u monitor:secret http://localhost:15672/api/health/checks/certificate-expiration/4/weeksA healthy endpoint returns HTTP 200 with {"status":"ok"}. A failed check returns HTTP 503 with {"status":"failed","reason":"..."}, so most load balancers can use the status code alone.
Two caveats:
guest account for this. It only works from localhost. Create a dedicated user: rabbitmqctl add_user monitor secret then rabbitmqctl set_user_tags monitor monitoring.If you want to go further than yes/no checks, the RabbitMQ monitoring API post covers the endpoints that return queue depth and message rates.
The quick answer at the top is the recommended setup. A few notes on the timing values:
start_period: 30s gives the node time to boot before failures count. A first boot that creates the data directory and enables plugins can take 10 to 20 seconds on a laptop.interval: 10s is plenty. Every CLI check starts a small Erlang node that joins the distribution to talk to RabbitMQ, so running it every second wastes CPU.timeout: 10s avoids false failures when the machine is busy.If you don't use the -management image or you don't need the full check, ping is a lighter alternative:
healthcheck:
test: ["CMD", "rabbitmq-diagnostics", "-q", "ping"]
interval: 10s
timeout: 5s
retries: 5For the full Docker setup (volumes, users, config files, clusters), see how to set up RabbitMQ with Docker and Docker Compose.
docker run -d --name rabbitmq \
--health-cmd "rabbitmq-diagnostics -q check_running" \
--health-interval 10s \
--health-timeout 10s \
--health-start-period 30s \
--health-retries 5 \
-p 5672:5672 -p 15672:15672 \
rabbitmq:4-management
docker inspect --format '{{.State.Health.Status}}' rabbitmqIn CI, you often want to block until the broker is ready, then run tests:
until docker exec rabbitmq rabbitmq-diagnostics -q check_running; do
echo "Waiting for RabbitMQ..."
sleep 2
donerabbitmqctl await_startup does the same thing in one command and returns once the node has fully started.
Kubernetes is where health checks matter most, and where the wrong check causes the most damage.
The RabbitMQ Cluster Operator configures a TCP check on the AMQP port as the readinessProbe and no livenessProbe at all. The monitoring guide calls this the best practice. If you write your own StatefulSet, copy it:
readinessProbe:
tcpSocket:
port: amqp
initialDelaySeconds: 10
periodSeconds: 10
timeoutSeconds: 5
failureThreshold: 3A liveness probe restarts the container when it fails. RabbitMQ nodes can be slow for good reasons: syncing a quorum queue after a restart, recovering a large message store, waiting for peers during a cluster-wide restart. A liveness probe that fires during any of these kills the node, which makes recovery slower, which makes the probe fire again. If you really need one, use rabbitmq-diagnostics -q ping with a generous failureThreshold, never a check that fails on alarms.
Use podManagementPolicy: Parallel. With OrderedReady, Kubernetes waits for pod 0 to be ready before starting pod 1. But a clustered RabbitMQ node may wait for its peers before it becomes ready, so a full restart can deadlock. The docs explicitly say OrderedReady is not recommended with RabbitMQ.
Each rabbitmq-diagnostics call starts an Erlang VM, connects to the node and shuts down. Every few seconds on every pod, that adds noticeable CPU load. Prefer the TCP check, or the HTTP endpoints if you need more than a port check.
A node can pass every check above while your system is in trouble. The checks don't tell you that:
For that you need metrics over time: queue depth, publish and deliver rates, consumer counts. The usual setup is the Prometheus plugin with Grafana, covered in our list of RabbitMQ monitoring tools.
For Docker Compose and readiness, rabbitmq-diagnostics -q check_running (optionally with check_local_alarms). For liveness, rabbitmq-diagnostics -q ping or no liveness probe at all. On Kubernetes, a TCP check on port 5672 as the readiness probe.
With the management plugin enabled: http://<host>:15672/api/health/checks/alarms, /api/health/checks/local-alarms, /api/health/checks/port-listener/5672 or /api/health/checks/virtual-hosts. They return 200 when healthy and 503 when not, and need a user with the monitoring tag.
The most common causes: the check runs before the node finished booting (add start_period), the timeout is too short on a busy machine, or the command is wrong (rabbitmqctl status without -q prints a lot but works; node_health_check is a no-op in modern versions). Run the command manually with docker exec to see its output.
rabbitmqctl status a good health check?It works, but rabbitmq-diagnostics -q status is the intended command, and check_running gives a clearer pass/fail answer.
For readiness or alerting, yes: publishers are blocked. For liveness, no: restarting the node won't free memory faster than letting consumers drain the queues, and it disconnects every client.
Interactive charts for every queue, ready the moment you connect. No Prometheus or Grafana required.
Explore my metricsAvailable on Windows, Mac, and Linux.
RabbitMQ tutorialThe RabbitMQ Management UI: a complete guideHow to enable the RabbitMQ management plugin, open the UI on port 15672 (Docker too), log in, and what each tab does, plus its limits.
RabbitMQ tutorialRabbitMQ retry queue vs dead letter queue: what's the difference?A retry queue holds a failed RabbitMQ message before another attempt, a dead-letter queue holds it once it should no longer be processed. Learn when to use each, how to combine them, and how they differ from requeue.
RabbitMQ tutorialRabbitMQ exponential backoff: how to retry messages with increasing delaysHow to implement exponential backoff retries in RabbitMQ with TTL retry queues and dead-letter exchanges. Track attempts with an x-retry-count header, choose retry delays, and send final failures to a DLQ.
RabbitMQ tutorialWhat is AMQP? The Advanced Message Queuing Protocol explainedLearn what AMQP (Advanced Message Queuing Protocol) is, how it works, its core concepts, why it powers RabbitMQ, and how it compares to alternatives like MQTT, STOMP, and Kafka.
RabbitMQ tutorialBuilding an event bus with RabbitMQLearn how to design a decoupled event bus using a RabbitMQ topic exchange, with practical routing key conventions, durable queues, and animated diagrams showing message flow.
RabbitMQ tutorialRabbitMQ Retry Pattern: How to Retry Failed MessagesHow to retry failed messages in RabbitMQ without infinite requeue loops. Compare retry queues with TTL, exponential backoff and the delayed message exchange, cap retry attempts, and send final failures to a dead-letter queue.