Alerting on queue depth and consumer lag in RabbitMQ - Commands & Configuration

Introduction

Queues in RabbitMQ hold messages waiting to be processed. Sometimes, too many messages build up or consumers fall behind. Alerting on queue depth and consumer lag helps you fix problems before they affect your app.

When your app slows down because messages pile up in the queue.

When consumers stop processing messages and lag behind.

When you want to keep your message system healthy and responsive.

When you need to know if a queue is overloaded or stuck.

When you want to automate alerts instead of checking manually.

Config File - rabbitmq.conf

rabbitmq.conf

management.load_definitions = /etc/rabbitmq/definitions.json

# Enable Prometheus metrics for monitoring
prometheus.tcp.port = 9419

# Configure alert thresholds
alert.queue_depth_threshold = 1000
alert.consumer_lag_threshold = 500

This config enables management plugin definitions and Prometheus metrics for monitoring RabbitMQ.

The alert.queue_depth_threshold sets the max messages allowed in a queue before alerting.

The alert.consumer_lag_threshold sets the max lag allowed for consumers before alerting.

Commands

Enable the Prometheus plugin to expose RabbitMQ metrics for monitoring queue depth and consumer lag.

Terminal

rabbitmq-plugins enable rabbitmq_prometheus

Expected Output

The following plugins have been enabled:

rabbitmq_prometheus

Applying plugin configuration to rabbit@localhost... done.

List all queues with their current message count and number of consumers to check queue depth and consumer presence.

Terminal

rabbitmqctl list_queues name messages consumers

Expected Output

Listing queues ...

queue1	1200	2

queue2	300	1

queue3	0	0

...done.

Fetch queue details from RabbitMQ management API to see messages ready and consumers for alerting logic.

Terminal

curl -s http://localhost:15672/api/queues | jq '.[] | {name: .name, messages_ready: .messages_ready, consumers: .consumers}'

Expected Output

{

  "name": "queue1",

  "messages_ready": 1200,

  "consumers": 2

}

{

  "name": "queue2",

  "messages_ready": 300,

  "consumers": 1

}

{

  "name": "queue3",

  "messages_ready": 0,

  "consumers": 0

}

List consumers with their unacknowledged messages to detect consumer lag.

Terminal

rabbitmqctl list_consumers queue consumer_tag channel_pid ack_required unacked_messages

Expected Output

Listing consumers ...

queue1	consumer1	<0.1234.0>	true	600

queue1	consumer2	<0.1235.0>	true	700

queue2	consumer3	<0.1236.0>	true	100

...done.

Key Concept

If you remember nothing else from this pattern, remember: monitoring queue message counts and unacknowledged messages helps catch slow or stuck consumers early.

Common Mistakes

Checking only total messages without considering unacknowledged messages.

You might miss consumer lag because messages are delivered but not yet processed.

Check both messages_ready and unacknowledged messages to get full queue and consumer lag picture.

Not enabling the Prometheus plugin or management API before trying to monitor metrics.

No metrics or API data will be available, so alerts cannot be triggered.

Enable rabbitmq_prometheus plugin and management plugin to expose metrics and API.

Setting alert thresholds too high or too low without testing.

Alerts may trigger too often or never trigger, causing alert fatigue or missed problems.

Start with reasonable thresholds and adjust based on normal queue behavior.

Summary

Enable the Prometheus plugin to expose RabbitMQ metrics for monitoring.

Use rabbitmqctl and management API to check queue message counts and consumer lag.

Set alert thresholds to notify when queues grow too large or consumers fall behind.