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 - ブローカーレベルの設定（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 に記載されているアンチパターンも検索してください。

• 同期的な produce 呼び出し（.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：定期的なパフォーマンスレビュー

ユーザー：「ステージングの Kafka パフォーマンス設定をレビューしてください」

実行内容：

1. ステージング内のすべてのトピックについて、クラスター側の設定を確認する
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 エージェントがオフラインです。 解決策：まず 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