kafka-topic-audit

Kafka トピック設定の監査

すべてのトピック設定を本番環境のベストプラクティスと照合して監査します。設定ミスのあるトピックは、Kafka のデータ損失の最大の原因です。エンジニアがトピックを作成したあと、設定の調整を忘れてしまうためです。

対象環境：$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. すべてのトピックを取得する：設定も取得します
3. 各トピックを監査する：ベストプラクティスと照合します（references/audit-rules.md を参照）
4. メタデータを相互参照する：完全性を確認します
5. 孤立したトピックを検出する：コンシューマーがいないトピックを確認します
6. 結果を報告する：優先順位を付けた推奨事項を示します

ステップ 1：環境の概要

Lenses MCP の check_environment_health ツールを使用して、概要をすばやく確認します。

• ブローカー数、トピック数、コンシューマー数、コネクター数
• Lenses によって報告された既存の問題

期待される出力：ブローカー数、トピック数、コンシューマー数を含む環境の健全性の概要。

検証：環境が健全でない、または接続できない場合は、先に進まず、接続の問題を報告してください。

ステップ 2：すべてのトピックを取得する

Lenses MCP の list_topics ツールを使用して、すべてのトピックとその設定を 1 回の呼び出しで取得します。

詳細な調査が必要なトピックには、以下を使用します。

• get_topic：パーティションとコンシューマーを含む詳細な設定
• get_topic_broker_configs：ブローカーレベルの設定オーバーライド
• get_topic_partitions：パーティションレベルのメッセージ数とバイト数

期待される出力：設定を含むトピックの完全な一覧。トピックが 0 件の場合は、その旨を報告して終了してください。

ステップ 3：設定を監査する

各トピックについて、references/audit-rules.md のしきい値と照合します。

• レプリケーション係数 - RF=1 は重大、RF=2 は本番環境では警告です
• 保持ポリシー - 無制限の増加、短すぎる保持期間、または過度に長い保持期間
• パーティション数 - 単一パーティションによるボトルネック、または過剰なパーティション数
• コンパクション設定 - キーなしでの compact、状態トピックに対する delete
• 命名規則 - {domain}.{entity}.{event} のパターンに従う必要があります

ステップ 4：メタデータの完全性

Lenses MCP の list_topic_metadata ツールを使用して、以下を確認します。

• 説明がないトピック
• タグがないトピック
• 登録済みのスキーマ（キーまたは値）がないトピック

フィルター（is_compacted、has_records）を指定して list_datasets を使用し、異常を見つけます。

ステップ 5：孤立したトピックの検出

各トピックについて、list_consumer_groups_by_topic を使用してアクティブなコンシューマーがいるか確認します。

• 警告：コンシューマーグループが 0 件のトピック（孤立または使用停止の可能性があります）
• 提案：非アクティブまたは空のコンシューマーグループのみがあるトピック

ステップ 6：整合性チェック

• 同じドメイン内で保持ポリシーが異なるトピックにフラグを立てます
• 同じドメイン内でレプリケーション係数が異なるトピックにフラグを立てます
• 同じドメイン内でシリアライズ形式が一貫していないトピックにフラグを立てます

成功基準

定量的基準

• トピック関連のクエリの 90% で実行される（表現を 10～20 種類変えてテストします）
• 15 回未満の MCP ツール呼び出しで完全な監査を完了する
• 実行あたりの MCP 呼び出しの失敗が 0 件

定性的基準

• ユーザーからの追加質問がなくても、レポートに基づいて対応できます
• 実行ごとに重大度の分類（重大／警告／提案）が一貫している
• すべての指摘に具体的な修正手順が含まれている

例

例 1：定期的な週次監査

ユーザーの依頼：「ステージング環境のトピックを監査してください」

操作：

1. Lenses MCP を使用してステージング環境の健全性を確認します
2. すべてのトピックと設定を取得します
3. references/audit-rules.md のルールと照合して、各トピックを監査します
4. メタデータの完全性と孤立したトピックを確認します 結果：優先順位を付けた指摘を含む完全な監査レポート

例 2：デプロイ前のチェック

ユーザーの依頼：「私のトピック設定が本番環境で使用できる状態か確認してください」

操作：

1. RF < 3、無制限の保持期間、単一パーティションがないか、すべてのトピックを監査します
2. 本番環境へのデプロイを妨げる重大な問題にフラグを立てます 結果：本番稼働前に修正が必要な重大な問題を示すレポート

例 3：特定のトピックを調査する

ユーザーの発言：「orders.payment.completed トピックは正しく設定されていますか？」

実行内容：

1. get_topic を使用して、特定のトピックの詳細設定を取得します
2. get_topic_broker_configs を使用して、ブローカーレベルのオーバーライドを確認します
3. メタデータとコンシューマーグループを検証します 結果：1 つのトピックに関する、すべての調査結果を含む詳細なレポート

トラブルシューティング

Lenses MCP への接続に失敗する

原因：環境名が正しくないか、Lenses エージェントがオフラインです。 解決方法：まず check_environment_health を実行します。環境名が list_environments の返す名前と一致していることを確認します。

トピックが返されない

原因：環境は存在しますが、トピックがないか、権限が制限されています。 解決方法：Lenses UI でクラスターにトピックがあることを確認します。Lenses エージェントに読み取りアクセス権があることを確認します。

メタデータエンドポイントが空の結果を返す

原因：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