死信队列分析器（Dead Letter Queue Analyzer）

不要再忽视你的死信队列。分析 DLQ 中的消息，识别失败模式、定位根本原因、判断哪些消息可重放，并生成修复方案——将你的 DLQ 从一个“黑洞”转变为一条可操作的错误流。

适用场景：输入 “analyze DLQ”、“dead letter queue growing”、“why are messages failing”、“replay failed messages”、“DLQ backlog”、“message processing failures”，或当未处理消息持续积压时。

命令

1. analyze — 对 DLQ 消息进行分类

步骤 1：读取 DLQ 消息

AWS SQS：

aws sqs receive-message 
  --queue-url "$DLQ_URL" 
  --max-number-of-messages 10 
  --attribute-names All 
  --message-attribute-names All | python3 -c "
import json, sys
msgs = json.load(sys.stdin).get('Messages', [])
for m in msgs:
    body = json.loads(m['Body']) if m['Body'].startswith('{') else m['Body']
    attrs = m.get('Attributes', {})
    print(f'ID: {m["MessageId"]}')
    print(f'  Received count: {attrs.get("ApproximateReceiveCount", "?")}')
    print(f'  First received: {attrs.get("ApproximateFirstReceiveTimestamp", "?")}')
    print(f'  Body preview: {str(body)[:200]}')
    print()
"

# 统计 DLQ 当前深度
aws sqs get-queue-attributes --queue-url "$DLQ_URL" 
  --attribute-names ApproximateNumberOfMessages | python3 -c "
import json, sys
attrs = json.load(sys.stdin)['Attributes']
print(f'DLQ depth: {attrs["ApproximateNumberOfMessages"]} messages')
"

RabbitMQ：

# 列出 DLQ 队列
rabbitmqctl list_queues name messages | grep -i "dead|dlq|error"

# 查看消息内容（peek）
rabbitmqadmin get queue="dead_letter_queue" count=10 2>/dev/null

Kafka：

# 从 DLT（死信主题）读取消息
kafka-console-consumer --bootstrap-server $KAFKA_BROKER 
  --topic "$DLT_TOPIC" --from-beginning --max-messages 20 
  --property print.headers=true --property print.timestamp=true

步骤 2：按失败原因归类

根据失败原因对 DLQ 消息进行分组：

# 按错误模式对消息进行分组
from collections import Counter
errors = Counter()
for msg in dlq_messages:
    # 从消息属性或 Header 中提取错误原因
    error = msg.get('error_reason', msg.get('x-death-reason', 'unknown'))
    errors[error] += 1

for error, count in errors.most_common(10):
    print(f'{count:>5}x  {error}')

步骤 3：生成分析报告

# DLQ 分析报告

## 概览
- 队列名称：orders-processing-dlq
- 总消息数：1,247 条
- 最早消息：3 天前
- 增长速率：约 400 条/天（呈上升趋势）

## 失败类别统计
| 类别 | 数量 | 占比 | 是否可重放 | 根本原因 |
|----------|-------|---|------------|------------|
| Timeout | 823 | 66% | ✅ | 自周二发布以来数据库慢查询导致处理超时 |
| Schema error | 312 | 25% | ✅（修复后） | 新增字段 `currency` 未在消费者 Schema 中定义 |
| Poison message | 67 | 5% | ❌ | 价格计算中出现 NullPointerException |
| Permission | 45 | 4% | ✅（修复后） | 服务账号 Token 已过期 |

## 根本原因分析
主要问题：数据库慢查询引发处理超时（占全部失败的 66%）
- 起始时间：UTC 时间周二 14:30（与发布事件高度相关）
- 影响范围：823 笔订单滞留在 DLQ 中

## 修复方案
1. **优化数据库性能** —— 为 orders.status 字段添加缺失索引（立即执行）
2. **重放超时类消息**（823 条）—— 安全，所有操作具备幂等性
3. **更新消费者 Schema**，支持 `currency` 字段（影响 312 条消息）
4. **轮换服务账号 Token**（影响 45 条消息）
5. **修复 OrderPriceCalculator.java 第 67 行的 NullPointerException**（67 条消息 —— 需优先排查）
6. 配置 DLQ 深度告警（阈值：50 条消息）

2. replay — 生成重放脚本

# SQS：将消息从 DLQ 移回主队列
aws sqs start-message-move-task 
  --source-arn "$DLQ_ARN" 
  --destination-arn "$MAIN_QUEUE_ARN" 
  --max-number-of-messages-per-second 10

# 或选择性重放（仅限超时类错误）
# 先读取、过滤，再重新发送

3. monitor — 配置 DLQ 告警

生成 CloudWatch 告警 / Prometheus 告警，监控 DLQ 深度：

• 当 DLQ 深度 > 0 时告警（任何消息均为异常信号）
• 当增长速率 > N 条/小时时告警（表明问题正在活跃发生）
• 当最旧消息存在时间 > 24 小时时告警（消息开始失效）
• 配置仪表盘，展示 DLQ 深度随时间变化趋势 + 按类别分布

4. prevent — 提升消息处理健壮性

推荐以下改进措施，防止未来 DLQ 再次积压：

• 在转发至 DLQ 前，加入带退避机制（backoff）的重试逻辑
• 为消息添加幂等性 Key（idempotency key），保障重放安全
• 在消息 Header 中添加死信原因（dead letter reason），加速问题排查
• 为消息设置 TTL（Time-To-Live），避免无限堆积
• 在发布前增加 Schema 校验（源头拦截问题）