kafka-topic-audit

Kafka Topic 配置审计

根据生产环境最佳实践审计所有 Topic 配置。配置错误的 Topic 是 Kafka 数据丢失的首要原因——工程师创建 Topic 后常常忘记调整配置。

目标环境：$ARGUMENTS

工作流

复制此清单并跟踪进度：

Audit Progress:
- [ ] Step 1: Check environment health
- [ ] Step 2: Fetch all topics
- [ ] Step 3: Audit configurations against best practices
- [ ] Step 4: Check metadata completeness
- [ ] Step 5: Detect orphaned topics
- [ ] Step 6: Run consistency checks
- [ ] Step 7: Generate report

1. 检查环境运行状况，获取概览
2. 获取所有 Topic 及其配置
3. 审计每个 Topic，对照最佳实践（参见 references/audit-rules.md）
4. 交叉核对元数据，确保信息完整
5. 检测孤立 Topic，找出没有消费者的 Topic
6. 报告发现，并提供按优先级排序的建议

步骤 1：环境概览

使用 Lenses MCP check_environment_health 工具快速获取概览：

• Broker 数量、Topic 数量、消费者数量、连接器数量
• Lenses 标记的任何现存问题

预期输出：包含 Broker、Topic 和消费者数量的环境运行状况摘要。

验证：如果环境运行状况不佳或无法连接，请停止后续操作，并先报告连接问题。

步骤 2：获取所有 Topic

使用 Lenses MCP list_topics 工具，一次调用即可获取所有 Topic 及其配置。

对于需要深入检查的 Topic，请使用：

• get_topic 获取详细配置，包括分区和消费者
• get_topic_broker_configs 获取 Broker 级别的配置覆盖项
• get_topic_partitions 获取分区级别的消息数量和字节数

预期输出：包含配置的 Topic 完整列表。如果返回的 Topic 数量为 0，请报告此情况并停止。

步骤 3：审计配置

对于每个 Topic，依据 references/audit-rules.md 中的阈值进行检查：

• 复制因子——RF=1 属于严重问题，在生产环境中 RF=2 属于警告
• 保留策略——无限增长、保留时间过短或过长
• 分区数——单分区瓶颈或分区过多
• 压缩设置——启用压缩但没有键，状态 Topic 使用 delete 策略
• 命名约定——必须遵循 {domain}.{entity}.{event} 模式

步骤 4：元数据完整性

使用 Lenses MCP list_topic_metadata 工具检查：

• 缺少描述的 Topic
• 缺少标签的 Topic
• 未注册 Schema（键或值）的 Topic

使用带筛选条件（is_compacted、has_records）的 list_datasets 查找异常。

步骤 5：检测孤立 Topic

对于每个 Topic，使用 list_consumer_groups_by_topic 检查是否有活跃消费者。

• 警告：没有消费者组的 Topic（可能已孤立或失效）
• 建议：只有非活跃或空消费者组的 Topic

步骤 6：一致性检查

• 标记同一域中保留策略不同的 Topic
• 标记同一域中复制因子不同的 Topic
• 标记同一域中序列化格式不一致的 Topic

成功标准

定量标准

• 能触发 90% 的 Topic 相关查询（使用 10–20 种不同表述进行测试）
• 在 15 次 MCP 工具调用以内完成完整审计
• 每次运行中 MCP 调用失败次数为 0

定性标准

• 报告可直接采取行动，无需用户补充提问
• 不同运行中的严重程度分类一致（严重/警告/建议）
• 每项发现都包含具体的修复步骤

示例

示例 1：每周例行审计

用户说：“对 staging 环境运行 Topic 审计”

操作：

1. 通过 Lenses MCP 检查 staging 环境运行状况
2. 获取所有 Topic 及其配置
3. 根据 references/audit-rules.md 中的规则审计每个 Topic
4. 检查元数据完整性和孤立 Topic 结果：生成包含按优先级排序的发现项的完整审计报告

示例 2：部署前检查

用户说：“检查我的 Topic 配置是否已满足生产环境要求”

操作：

1. 审计所有 Topic，检查 RF < 3、无限保留和单分区等情况
2. 标记所有会阻碍生产部署的严重问题 结果：生成报告，突出显示上线前必须修复的严重问题

示例 3：调查特定主题

用户说：“orders.payment.completed 主题配置正确吗？”

操作：

1. 使用 get_topic 获取特定主题的详细配置
2. 使用 get_topic_broker_configs 检查代理级别的覆盖配置
3. 验证元数据和使用者组 结果：针对单个主题的重点报告，包含所有调查发现

故障排查

Lenses MCP 连接失败

原因：环境名称不正确，或 Lenses Agent 已离线。 解决方案：首先运行 check_environment_health。确认环境名称与 list_environments 返回的名称一致。

未返回任何主题

原因：环境已存在，但没有主题，或权限受到限制。 解决方案：通过 Lenses UI 确认集群中是否有主题。检查 Lenses Agent 是否具有读取权限。

元数据端点返回空结果

原因：未配置 Schema Registry，或主题没有已注册的架构。 解决方案：这是有效的调查发现，应将其报告为缺少元数据，而不是视为错误。

输出格式

## Topic Audit Report

### Environment: {name}
- Brokers: X | Topics: Y | Consumer groups: Z

### Critical (must fix)
- [topic-name] Description of the issue
  Current: {current value} | Recommended: {recommended value}

### Warning (should fix)
- [topic-name] Description of the issue
  Current: {current value} | Recommended: {recommended value}

### Suggestion (consider improving)
- [topic-name] Description of the issue
  Recommendation: How to fix it

### Summary
- X critical issues found
- Y warnings found
- Z suggestions found
- Topics audited: N
- Orphaned topics: M