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 またはカスタムツールを使用）

成功基準

定量的

• DLQ 関連のクエリの 90％ で起動する（表現を変えた 10～20 件でテスト）
• 15 回未満のツール呼び出し（MCP ＋コードベース検索）でレビューを完了する
• 標準的な命名パターンに一致する DLQ トピックを 100％ 検出する

定性的

• 監視されていない 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