MQ 死信队列排查命令+告警配置模板

MQ 死信队列排查命令+告警配置模板

分为 RabbitMQ、RocketMQ、Kafka 三部分，命令可直接复制使用，告警适配监控平台（Prometheus/Grafana、ELK、自研告警）。

---

一、RabbitMQ

1. 快速排查命令（Linux）

1.1 查看所有队列及消息堆积数

# 列出队列名、就绪消息数、未确认消息数
rabbitmqctl list_queues name messages_ready messages_unacknowledged

1.2 过滤仅查看死信队列（DLQ）

# 匹配含 dlq 关键字的队列
rabbitmqctl list_queues | grep -i dlq

1.3 查看队列详细状态（含TTL、绑定交换机等配置）

rabbitmqctl list_queues name arguments | grep -i dlq

1.4 查看交换机（死信交换机DLX）

rabbitmqctl list_exchanges name type | grep -i dlx

2. 消息查看&重放（UI 为主，命令为辅）

UI 地址：http://MQ_IP:15672

1. Queues → 选中DLQ队列 → Get Messages 查看消息体、x-death 头部（死信原因）
2. 修复问题后，复制消息内容，重新投递到原业务队列。

3. 告警配置模板

3.1 监控指标

• 指标：queue_messages_ready（队列就绪消息数）
• 阈值：DLQ队列消息数 > 0 即触发告警

3.2 告警规则（Prometheus + AlertManager 示例）

groups:
- name: rabbitmq_dlq_alert
  rules:
  - alert: RabbitMQ_DLQ_Message_Exist
    expr: rabbitmq_queue_messages_ready{queue=~".*dlq.*"} > 0
    for: 10s
    labels:
      severity: error
    annotations:
      summary: "RabbitMQ 死信队列存在堆积消息"
      description: "队列名称: {{ $labels.queue }}, 消息数量: {{ $value }}"

3.3 简易脚本巡检（定时任务crontab）

#!/bin/bash
# rabbit_dlq_check.sh
DLQ_COUNT=$(rabbitmqctl list_queues | grep -i dlq | awk '{sum+=$2} END {print sum}')
if [ $DLQ_COUNT -gt 0 ];then
  echo "RabbitMQ 死信队列堆积消息数：$DLQ_COUNT，请及时排查！"
  # 此处可对接钉钉/企业微信/邮件告警接口
fi

添加定时任务：*/1 * * * * /bin/bash /path/rabbit_dlq_check.sh

---

二、RocketMQ

前置说明

• 工具路径：bin/mqadmin
• 死信Topic格式：%DLQ%${消费者组名}
• 需提前配置 NAMESRV_ADDR=ip:9876

1. 快速排查命令

1.1 配置NameServer环境变量（临时生效）

export NAMESRV_ADDR=192.168.1.100:9876

1.2 查看所有Topic，筛选死信队列

mqadmin topicList | grep DLQ

1.3 查看指定消费者组的消费进度（看DLQ堆积）

# -g 消费者组名
mqadmin consumerProgress -g CID_ORDER_GROUP

1.4 查看死信Topic状态、分区、消息量

# -t 死信完整Topic名
mqadmin topicStatus -t %DLQ%CID_ORDER_GROUP

1.5 根据MsgID查询消息全链路（核心追踪）

mqadmin queryMsgById -i 0A01016400002A9F0000000000000001

1.6 查看消息Key查询消息

mqadmin queryMsgByKey -t %DLQ%CID_ORDER_GROUP -k order_10086

2. 消息查看&重放

推荐使用 RocketMQ 控制台：

1. 死信队列菜单 → 选中消费者组，查看所有死信消息、重试次数、报错信息
2. 支持一键重发到原业务Topic，无需手动造数据。

3. 告警配置模板

3.1 监控指标

• 指标：死信Topic分区消息堆积量、消费偏移量差值
• 阈值：DLQ消息数 > 0 触发告警

3.2 定时巡检脚本

#!/bin/bash
# rocket_dlq_check.sh
export NAMESRV_ADDR=192.168.1.100:9876
# 替换为你的死信Topic
DLQ_TOPIC="%DLQ%CID_ORDER_GROUP"
# 统计消息堆积数
DLQ_NUM=$(mqadmin topicStatus -t $DLQ_TOPIC | awk 'NR>2{sum+=$4}END{print sum}')
if [ $DLQ_NUM -gt 0 ];then
  echo "RocketMQ 死信队列 $DLQ_TOPIC 堆积消息：$DLQ_NUM 条，请排查！"
  # 对接告警接口
fi

定时任务：*/1 * * * * /bin/bash /path/rocket_dlq_check.sh

3.3 云原生告警（RocketMQ-Exporter）

groups:
- name: rocketmq_dlq
  rules:
  - alert: RocketMQ_DLQ_Has_Msg
    expr: rocketmq_topic_diff{topic=~"%DLQ%.*"} > 0
    for: 10s
    labels:
      severity: error
    annotations:
      summary: "RocketMQ 死信队列出现消息堆积"
      description: "死信Topic: {{$labels.topic}}, 堆积量: {{$value}}"

---

三、Kafka（自定义DLQ Topic，无原生死信）

前置说明

• 工具路径：bin/kafka-*.sh
• 自定义DLQ命名规范：原topic-dlq，例：order-topic-dlq

1. 快速排查命令

1.1 列出所有Topic，筛选DLQ

# 替换为你的集群地址
kafka-topics.sh --bootstrap-server 192.168.1.101:9092 --list | grep -i dlq

1.2 查看DLQ Topic分区偏移量（计算堆积）

kafka-get-offsets.sh --bootstrap-server 192.168.1.101:9092 --topic order-topic-dlq

计算规则：最新offset - 消费offset = 堆积消息数

1.3 消费DLQ消息，查看内容+自定义Header（异常信息）

kafka-console-consumer.sh \
--bootstrap-server 192.168.1.101:9092 \
--topic order-topic-dlq \
--from-beginning \
--property print.headers=true \
--property print.value=true

1.4 查看消费者组偏移（确认消费停滞）

kafka-consumer-groups.sh \
--bootstrap-server 192.168.1.101:9092 \
--describe \
--group order-dlq-consumer-group

2. 消息重放

1. 方式1：消费DLQ消息，代码转发至原业务Topic
2. 方式2：命令行生产回原Topic

kafka-console-producer.sh --bootstrap-server 192.168.1.101:9092 --topic order-topic

3. 告警配置模板

3.1 监控指标

• 指标：kafka_consumergroup_lag（消费延迟/堆积）
• 阈值：DLQ主题消费延迟 > 0 触发告警

3.2 Prometheus 告警规则

groups:
- name: kafka_dlq_alert
  rules:
  - alert: Kafka_DLQ_Msg_Lag
    expr: kafka_consumergroup_lag{topic=~".*dlq.*"} > 0
    for: 10s
    labels:
      severity: error
    annotations:
      summary: "Kafka 自定义死信队列存在堆积"
      description: "Topic: {{$labels.topic}}, 堆积量: {{$value}}"

3.3 简易巡检脚本

#!/bin/bash
# kafka_dlq_check.sh
BS="192.168.1.101:9092"
DLQ_TOPIC="order-topic-dlq"
# 统计堆积（简易版，单分区适用）
LAG=$(kafka-consumer-groups.sh --bootstrap-server $BS --describe --group dlq-group | grep $DLQ_TOPIC | awk '{print $5}')
if [ $LAG -gt 0 ];then
  echo "Kafka 死信队列 $DLQ_TOPIC 堆积 $LAG 条消息"
  # 调用告警接口
fi

---

四、通用补充规范

1. 巡检频率：线上高并发业务统一 1分钟 巡检一次，及时发现死信突增
2. 告警渠道：优先钉钉/企业微信机器人 + 短信（紧急故障）
3. 排查优先级
   • 第一步：看数量（个别消息=偶发问题；批量突增=系统故障）
   • 第二步：看消息体 + 异常头（定位数据问题/代码问题）
   • 第三步：查应用日志、依赖服务（DB、接口、缓存）
4. 重放原则：修复BUG/脏数据后，再统一重放死信，禁止盲目重投。