kafka-perf-review

Kafka 性能配置审查

检查实时集群和代码库中的生产者与消费者配置，识别性能反模式。这些设置在所有 Kafka 客户端库中都相同（它们是 Kafka 协议属性）。

目标环境和路径：$ARGUMENTS（如果未指定路径，代码库扫描默认为 src/）

工作流

复制此检查清单并跟踪进度：

Performance Review Progress:
- [ ] Step 1: Inspect live cluster configs
- [ ] Step 2: Scan codebase for producer/consumer configs
- [ ] Step 3: Audit producer configs
- [ ] Step 4: Audit consumer configs
- [ ] Step 5: Cross-reference cluster and code configs
- [ ] Step 6: Generate report

1. 检查实时集群配置，使用 Lenses MCP
2. 扫描代码库中的生产者/消费者配置属性（参见 references/producer-defaults.md 和 references/consumer-defaults.md）
3. 审查生产者配置，并对照推荐值进行核查
4. 审查消费者配置，并对照推荐值进行核查
5. 交叉核对集群配置和代码配置
6. 报告发现，列出当前值、推荐值和权衡说明

第 1 步：检查实时集群

使用 Lenses MCP 工具检查集群侧的性能配置：

• get_topic - 影响性能的主题级配置（min.insync.replicas、compression.type、max.message.bytes）
• get_topic_broker_configs - Broker 级配置（message.max.bytes、replica.fetch.max.bytes、num.io.threads）
• get_topic_partitions - 分区间的消息分布（检测某个分区的字节数是否显著高于其他分区，以发现倾斜）
• get_dataset_message_metrics - 随时间变化的消息吞吐量，用于识别瓶颈或容量余量

预期输出：主题级性能配置、分区分布和吞吐量指标。

验证：如果 MCP 调用失败，请继续仅分析代码库，并在报告中注明此限制。

第 2 步：检查代码库

搜索代码库中的 Kafka 生产者和消费者配置属性。完整的生产者属性列表请参见 references/producer-defaults.md，消费者属性请参见 references/consumer-defaults.md。

同时搜索 references/producer-defaults.md 中列出的反模式：

• 同步生产消息调用（每次发送后调用 .get()、.result()、flush()）
• 缺少投递回调/错误处理程序
• 缺少优雅关闭/再平衡监听器

第 3 步：审查生产者配置

将找到的生产者配置与 references/producer-defaults.md 中的推荐值进行比较。重点关注：acks、batch.size、linger.ms、compression.type、enable.idempotence 和 retries。

第 4 步：审查消费者配置

将找到的消费者配置与 references/consumer-defaults.md 中的推荐值进行比较。重点关注：max.poll.records、max.poll.interval.ms、auto.offset.reset、enable.auto.commit 和 fetch.min.bytes。

成功标准

定量指标

• 能匹配 90% 的性能相关查询（使用 10-20 种不同表述进行测试）
• 在 15 次工具调用内完成审查（MCP + 代码库搜索）
• 每次运行的 MCP 调用失败次数为 0

定性指标

• 每项发现都列出当前值、推荐值和权衡说明
• 识别出的反模式均附有文件和行号引用
• 吞吐量影响估算（低/中/高）保持一致且准确

示例

示例 1：常规性能审查

用户说：“审查 staging 的 Kafka 性能配置。”

操作：

1. 检查 staging 中所有主题的集群侧配置
2. 扫描 src/ 中的生产者/消费者属性定义
3. 根据参考表交叉核对代码配置 结果：报告按属性列出发现，并估算吞吐量影响

示例 2：调查消费者速度慢的问题

用户说：“为什么我的消费者速度很慢？检查性能设置。”

操作：

1. 重点检查代码库中的消费者配置属性
2. 检查 max.poll.records、fetch.min.bytes 和 enable.auto.commit
3. 查找同步处理等反模式 结果：提供针对消费者侧瓶颈的报告及修复步骤

示例 3：针对特定范围的代码库审查

用户说：“检查 src/kafka/ 中生产环境的 Kafka 配置。”

操作：

1. 仅扫描 src/kafka/ 中的生产者和消费者配置
2. 与实时生产集群设置交叉比对 结果：针对特定目录中 Kafka 配置的专项报告

故障排除

在代码库中未找到 Kafka 配置属性

原因：代码库可能使用了隐藏原始 Kafka 属性的框架或封装层。 解决方案：搜索框架特定的配置模式（例如，Spring Boot application.yml、Django 设置）。报告所用的框架，并建议进行人工审查。

Lenses MCP 未返回主题数据

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

分区倾斜检测结果不明确

原因：主题吞吐量非常低，因此各分区的字节数相近。 解决方案：说明倾斜检测需要足够的吞吐量。对于低流量主题，请跳过倾斜检查，并在报告中注明。

输出格式

## Performance Review Report

### Cluster-Side Findings
- [topic-name] {property}: {current value}
  Recommendation: {recommended value} - {explanation}

### Codebase Findings (Producers)
- [file:line] {property} = {current value}
  Recommendation: {recommended value} - {explanation}

### Codebase Findings (Consumers)
- [file:line] {property} = {current value}
  Recommendation: {recommended value} - {explanation}

### Anti-Patterns
- [file:line] Description of the anti-pattern
  Recommendation: How to fix it

### Summary
- X producer issues found
- Y consumer issues found
- Z anti-patterns found
- Estimated throughput impact: low/medium/high