kafka-dlq-review

Kafka 死信队列审查

检查死信队列实现是否完整并符合最佳实践。DLQ 是每个 Kafka 消费者最终都需要处理的跨领域问题。大多数团队都是事后才实现它们，并且忘了对其进行监控。

目标环境：$ARGUMENTS

工作流

复制此清单并跟踪进度：

DLQ Review Progress:
- [ ] Step 1: Discover DLQ topics
- [ ] Step 2: Check DLQ topic configuration
- [ ] Step 3: Verify DLQ monitoring
- [ ] Step 4: Sample DLQ messages
- [ ] Step 5: Audit connector DLQ configs
- [ ] Step 6: Scan codebase for error handling
- [ ] Step 7: Generate report with maturity assessment

1. 发现 DLQ 主题：在集群中查找
2. 检查 DLQ 主题配置（保留时间、分区数）
3. 验证 DLQ 监控（消费者、告警）
4. 抽样检查 DLQ 消息，确认元数据完整
5. 审计连接器的 DLQ 配置
6. 扫描代码库，查找错误处理模式
7. 报告发现结果，并评估成熟度

步骤 1：发现 DLQ 主题

使用 Lenses MCP list_topics 工具，并根据命名约定筛选 DLQ 主题：

• *.dlq
• *.dead-letter
• *.error
• *.errors
• *.retry
• *-dlq
• *-dead-letter

还要使用 list_kafka_connectors 检查连接器配置中的 DLQ 主题名称。

预期输出：根据命名约定和连接器配置发现的 DLQ 主题列表。

验证：如果未发现任何 DLQ 主题，请在得出未实现 DLQ 的结论前，先在代码库中搜索错误主题配置。

步骤 2：检查 DLQ 主题配置

对于每个发现的 DLQ 主题，使用 get_topic 进行验证：

• 警告：保留时间过短（DLQ 消息的保留时间应长于源主题，以便调查）
• 警告：只有 1 个分区（DLQ 流量激增时可能成为瓶颈）
• 警告：副本因子低于源主题（DLQ 数据通常更需要妥善保留）
• 建议：对于重新处理会覆盖错误的 DLQ 主题，可考虑启用压缩

步骤 3：验证 DLQ 监控

对每个 DLQ 主题使用 list_consumer_groups_by_topic 检查：

• 严重：DLQ 主题没有消费者组（没有人监控失败消息）
• 警告：DLQ 消费者组处于非活动或空状态（监控可能已停止）
• 建议：DLQ 消费者组应包含告警或仪表板服务

使用 get_dataset_message_metrics 检查 DLQ 消息速率：

• 警告：DLQ 消息速率持续偏高（表明上游存在问题）
• 警告：DLQ 消息速率随时间持续上升（系统健康状况正在恶化）

步骤 4：抽样检查 DLQ 消息

使用 Lenses MCP execute_sql 工具，从 DLQ 主题中抽样检查消息：

SELECT * FROM `{dlq-topic}` LIMIT 10

检查 DLQ 消息是否包含完整元数据：

必需元数据

• 严重：原始主题名称（消息来源）
• 严重：错误消息（出了什么问题）
• 警告：原始分区和偏移量（用于追踪）
• 警告：原始时间戳（消息的生成时间）
• 建议：堆栈跟踪（用于调试）
• 建议：重试次数（尝试处理的次数）
• 建议：消费者组 ID（处理失败的消费者）

步骤 5：审计连接器的 DLQ 配置

使用 list_kafka_connectors 和 get_kafka_connector_target_definition 检查：

• 严重：连接器设置了 errors.tolerance=all，却未设置 errors.deadletterqueue.topic.name（会静默丢弃消息）
• 警告：连接器设置了 errors.tolerance=none，却未配置 DLQ（遇到任何错误都会停止，且没有恢复途径）
• 建议：启用 errors.deadletterqueue.context.headers.enable=true，以提供更丰富的错误上下文
• 建议：启用 errors.log.enable=true，以记录错误日志

第 6 步：代码库检查

搜索代码库中的错误处理和 DLQ 模式：

• DLQ 生产者配置（搜索 dlq、dead.letter、error.topic）
• 路由到 DLQ 前的重试逻辑（搜索 retry、backoff、max_retries）
• 消费者中的错误处理（搜索 poll、consume、process 周围的异常处理）
• 重新处理机制（用于重放 DLQ 消息的脚本或工具）

标记：

• 警告：消息处理过程中没有错误处理的消费者
• 警告：未尝试重试便立即路由到 DLQ
• 建议：没有重新处理 DLQ 消息的机制（通过 Lenses 使用 resend_message 或自定义工具）

成功标准

定量标准

• 对 90% 的 DLQ 相关查询触发（使用 10–20 种不同表述进行测试）
• 在 15 次工具调用以内完成审查（MCP + 代码库搜索）
• 发现 100% 符合标准命名模式的 DLQ 主题

定性标准

• 始终将未监控的 DLQ 主题标记为严重问题
• 按每个 DLQ 主题评估元数据完整性，并提供清晰的检查清单
• 一致地应用成熟度评估（无／基础／完整）

示例

示例 1：全面审计 DLQ

用户说：“审计生产环境中的所有死信队列”

操作：

1. 按命名约定发现所有 DLQ 主题
2. 检查每个 DLQ 主题的配置和监控
3. 抽样检查消息的元数据完整性
4. 审计连接器的 DLQ 配置
5. 扫描代码库中的错误处理模式 结果：全面报告所有消费者和连接器的 DLQ 成熟度

示例 2：调查消息失败

用户说：“消息进入了 DLQ，出了什么问题？”

操作：

1. 使用 execute_sql 抽样检查最近的 DLQ 消息
2. 检查错误消息和堆栈跟踪
3. 追溯到源主题和消费者组
4. 检查 DLQ 消息速率趋势 结果：DLQ 消息流的根本原因分析

示例 3：检查 DLQ 覆盖情况

用户说：“我们的所有消费者都处理了 DLQ 吗？”

操作：

1. 列出 Lenses 中的所有消费者组
2. 检查哪些组有对应的 DLQ 主题
3. 扫描代码库中消费者的错误处理逻辑
4. 报告缺少 DLQ 实现的消费者 结果：显示每个消费者 DLQ 成熟度的覆盖情况报告

故障排查

未找到 DLQ 主题

原因：DLQ 主题可能使用非标准命名，或者尚未实现 DLQ。 解决方案：在代码库中搜索错误主题配置。还要检查连接器配置中是否有不符合常见模式的 DLQ 主题名称。

DLQ 消息没有元数据

原因：DLQ 生产者未包含标头或结构化错误信息。 解决方案：将此问题报告为严重发现。没有元数据的 DLQ 消息很难调查和重新处理。

execute_sql 返回二进制／不可读数据

原因：DLQ 消息可能使用了与预期不同的序列化格式。 解决方案：尝试在查询中指定格式。报告序列化格式问题，并建议统一格式。

输出格式

## DLQ Review Report

### Environment: {name}

### DLQ Topics Discovered
| DLQ Topic | Source Topic | Retention | Partitions | Has Consumers | Message Rate |
|-----------|-------------|-----------|------------|--------------|-------------|
| topic.dlq | topic | 7d | 3 | Yes | 12/hr |

### Critical (must fix)
- [topic/connector/file] Description of the issue
  Impact: {what could go wrong}
  Remediation: {how to fix}

### Warning (should fix)
- [topic/connector/file] Description of the issue
  Remediation: {how to fix}

### Suggestion (consider improving)
- [topic/connector/file] Description of the suggestion
  Recommendation: {how to improve}

### DLQ Metadata Completeness
| DLQ Topic | Original Topic | Error Message | Partition/Offset | Timestamp | Stack Trace | Retry Count |
|-----------|---------------|--------------|-----------------|-----------|-------------|-------------|
| topic.dlq | ✅ | ✅ | ⚠️ | ⚠️ | ❌ | ❌ |

### Maturity Assessment
| Consumer/Connector | DLQ Status | Maturity |
|-------------------|-----------|---------|
| consumer-name | Configured with monitoring | Complete |
| connector-name | Configured without monitoring | Basic |
| other-consumer | No DLQ | None |

### Summary
- X DLQ topics found
- Y consumers/connectors without DLQ
- Z unmonitored DLQ topics
- Overall DLQ maturity: none/basic/complete