RabbitMQ health checks: CLI, HTTP API, Docker and Kubernetes

•8 min read•RabbitMQ tutorial

RabbitMQ health checks: CLI, HTTP API, Docker and Kubernetes

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.

Quick answer: Docker Compose healthcheck

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_healthy

check_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 five levels of health checks

The official monitoring guide describes health checks as stages. Each stage checks more than the one before, and costs a bit more.

StageCommandWhat it checksGood for
1rabbitmq-diagnostics -q pingThe Erlang VM is up and the node answers CLI toolsLiveness, "is the process alive"
2rabbitmq-diagnostics -q statusStage 1, plus the node can report its statusBasic sanity checks
3rabbitmq-diagnostics -q check_running and check_local_alarmsRabbitMQ is running and no memory or disk alarm is blocking publishersReadiness, Docker Compose
4rabbitmq-diagnostics -q check_port_connectivityEvery listener (AMQP, management, Prometheus…) accepts TCP connectionsLoad balancers, smoke tests
5rabbitmq-diagnostics -q check_virtual_hostsEvery virtual host is running on the nodePost-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.

Why "deeper" is not always better

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.

The legacy node_health_check

You 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.

CLI health checks in detail

ping

rabbitmq-diagnostics -q ping

The cheapest check. It succeeds as soon as the Erlang runtime is up and reachable by CLI tools, even if RabbitMQ itself is still booting.

check_running and check_local_alarms

rabbitmq-diagnostics -q check_running && rabbitmq-diagnostics -q check_local_alarms

This 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.

check_port_connectivity

rabbitmq-diagnostics -q check_port_connectivity

Opens 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 listeners

check_virtual_hosts

rabbitmq-diagnostics -q check_virtual_hosts

Fails 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.

Before a restart: check_if_node_is_quorum_critical

rabbitmq-diagnostics -q check_if_node_is_quorum_critical

Not 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.

HTTP API health checks

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/weeks

A 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:

  • These endpoints depend on the management plugin. If the plugin is down, the check fails even though AMQP clients may be fine.
  • Don't use the 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.

Docker health checks

Docker Compose

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: 5

For the full Docker setup (volumes, users, config files, clusters), see how to set up RabbitMQ with Docker and Docker Compose.

Plain Docker

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}}' rabbitmq

Waiting for RabbitMQ in a script

In 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
done

rabbitmqctl await_startup does the same thing in one command and returns once the node has fully started.

Kubernetes probes

Kubernetes is where health checks matter most, and where the wrong check causes the most damage.

What the RabbitMQ docs recommend

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: 3

Why no liveness probe?

A 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.

Pod management policy

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.

Avoid CLI probes at high frequency

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.

Health checks are not monitoring

A node can pass every check above while your system is in trouble. The checks don't tell you that:

  • a queue has 2 million messages and keeps growing,
  • consumers disconnected an hour ago,
  • the dead-letter queue is filling up,
  • publish rate doubled after the last deploy.

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.

FAQ

What is the best health check for RabbitMQ?

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.

What is the RabbitMQ health check URL?

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.

Why does my RabbitMQ Docker health check always fail?

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.

Is 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.

Should a health check fail when a memory alarm is raised?

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.

Monitor RabbitMQ without the setup

Interactive charts for every queue, ready the moment you connect. No Prometheus or Grafana required.

Explore my metrics

Available on Windows, Mac, and Linux.

Read more RabbitMQ tutorials

The RabbitMQ Management UI: a complete guideRabbitMQ 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 retry queue vs dead letter queue: what's the difference?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 exponential backoff: how to retry messages with increasing delaysRabbitMQ 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.What is AMQP? The Advanced Message Queuing Protocol explainedRabbitMQ 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.Building an event bus with RabbitMQRabbitMQ 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 Retry Pattern: How to Retry Failed MessagesRabbitMQ 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.