mcpField
K
kafka-consumer-lag

kafka-consumer-lag

github.com/lensesioデータ・データベース6660 回インストール10 週間前に更新
リポジトリ

kafka-consumer-lag について

kafka-consumer-lagは、Kafkaのコンシューマー遅延やインシデントを調査するエンジニア向けのスキルです。グループの状態とパーティション別の遅延を調べ、分布やスループットの情報から原因を診断し、グループごとの対処案を示します。

主な機能

  1. 01コンシューマーグループの状態と遅延を取得
  2. 02高遅延、アイドル、リバランス中のグループを特定
  3. 03パーティションとスループットから原因を診断
  4. 04グループごとの対処案を提示
  5. 05メッセージを抽出してデータフローを確認

活用シーン

  1. 01コンシューマーの滞留増加を調査
  2. 02特定トピックの遅延を確認
  3. 03コミット済みオフセットがある停止グループを特定

MCP 対応

Lenses MCPでコンシューマーグループ、トピックパーティション、メッセージスループットを確認し、SQLで直近のメッセージを抽出して遅延の診断に役立てます。

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/lensesio/agentic-engineering-for-apache-kafka --skill kafka-consumer-lag

インストール後、Claude Code で/kafka-consumer-lagを入力して読み込まれたか確認します。

同梱ファイルreferences/test-cases.md

詳細

Kafka コンシューマーラグ分析

すべてのグループのコンシューマーグループラグを分析し、考えられる原因を診断します。コンシューマーラグは、Kafka で最もよく監視されるメトリクスであり、インシデント発生時にエンジニアが最初に確認する項目です。

対象環境：$ARGUMENTS

ワークフロー

このチェックリストをコピーして、進捗を記録してください。

Lag Analysis Progress:
- [ ] Step 1: Fetch all consumer groups
- [ ] Step 2: Identify problematic groups
- [ ] Step 3: Diagnose root causes
- [ ] Step 4: Generate report
  1. すべてのコンシューマーグループを取得し、状態とラグ情報を確認する
  2. 問題のあるグループを特定する（ラグが大きい、アイドル状態、リバランス中）
  3. パーティションとスループットのデータを使って根本原因を診断する
  4. グループごとの対処手順とともに調査結果を報告する

ステップ 1：コンシューマーグループを取得する

Lenses MCP の list_consumer_groups ツールを使い、次の情報を含むすべてのコンシューマーグループを取得します。

  • グループの状態（Stable、Rebalancing、Empty、Dead）
  • トピック・パーティションごとのラグ
  • アクティブなメンバー数
  • コーディネーター情報

特定のトピックを分析する場合は、list_consumer_groups_by_topic を使って対象を絞り込みます。

想定される出力：状態、ラグ、メンバー数を含むすべてのコンシューマーグループの一覧。

検証：コンシューマーグループが返されない場合は、その結果を報告して終了します。クラスターにアクティブなコンシューマーが存在しない可能性があります。

ステップ 2：問題のあるグループを特定する

次のカテゴリに該当するコンシューマーグループにフラグを付けます。

重大
  • オフセットがコミットされているにもかかわらず、状態が Dead または Empty のグループ（コンシューマーが停止しています）
  • 時間の経過とともにラグが増加しているグループ（get_topic_partitions を使って、現在のラグとパーティションの終了オフセットを比較します）
警告
  • Rebalancing 状態のグループ（メッセージの消費が一時停止しています）
  • パーティション割り当てに偏りがあるグループ（一部のコンシューマーに、他より大幅に多くのパーティションが割り当てられています）
  • コミット済みオフセットがないグループ（コンシューマーが正常に起動したことがない可能性があります）
提案
  • パーティション数に対してメンバー数が非常に多いグループ（アイドル状態のコンシューマーがいます）
  • 最近メッセージのないトピックを消費しているグループ（get_dataset_message_metrics を使ってプロデューサーのスループットを確認します）

ステップ 3：根本原因を診断する

問題のあるグループごとに、考えられる原因を特定します。

ラグが増加 ＋ プロデューサーのレートが安定
  • コンシューマーのスループットがボトルネックになっています
  • 対処：コンシューマーをスケールし、max.poll.records を増やし、メッセージあたりの処理時間を短縮し、同期的なブロッキング呼び出しがないか確認します
ラグの急増 ＋ リバランス中
  • リバランスによってメッセージの消費が一時停止しています
  • 対処：協調的スティッキーアサイナーに切り替え、session.timeout.ms を増やし、max.poll.interval.ms に関するリスクを軽減します
単一のパーティションでラグが発生（他は問題なし）
  • ホットパーティションまたはキーの偏りです
  • 対処：パーティショニング戦略を見直し、ホットキーを確認し、カスタムパーティショナーを検討します
すべてのパーティションで同程度のラグが発生
  • コンシューマー全体の処理速度が低下しています
  • 対処：コンシューマーの処理をプロファイリングし、外部依存関係（データベース、API 呼び出し）を確認し、コンシューマーインスタンスを増やします
ラグはゼロだがグループは Empty
  • コンシューマーがクラッシュしたか、停止・削除されています
  • 対処：コンシューマープロセスの正常性を確認し、必要に応じて再起動し、古いグループをクリーンアップします

ステップ 4：データフローを検証する

Lenses MCP の execute_sql ツールを使って、ラグが発生しているトピックから最近のメッセージをサンプリングします。

SELECT * FROM {topic} LIMIT 5

これにより、トピックにアクティブなプロデューサーが存在し、メッセージが流れていることを確認できます。

成功基準

定量的
  • ラグに関するクエリの 90% でトリガーされる（表現を変えた 10～20 件でテスト）
  • 12 回未満の MCP ツール呼び出しで分析を完了する
  • 1 回の実行あたり MCP 呼び出しの失敗が 0 件
定性的
  • フラグを付けた各グループに、具体的な診断結果と対処方法がある
  • 症状と根本原因を区別したレポートになっている
  • 同じ環境で再実行した場合に、一貫した結果が得られる

例

例 1：インシデント調査

ユーザーの発言：「コンシューマーの処理が遅れています。ラグを確認してください」

対応：

  1. 対象環境のすべてのコンシューマーグループを取得する
  2. 合計ラグの降順で並べ、最も問題の大きいグループを特定する
  3. 重大なグループごとに根本原因を診断する 結果：グループごとの診断と対処方法を含む、優先順位付きのレポート
例 2：トピック固有のラグ確認

ユーザーの発言：「orders.payment.completed のコンシューマーラグを確認してください」

アクション：

  1. list_consumer_groups_by_topic を使用して、そのトピックを消費しているグループを取得します
  2. パーティションレベルのラグ分布を確認します
  3. execute_sql でデータフローを検証します 結果：単一トピックのコンシューマーグループに焦点を当てたレポート
例 3：古いグループのクリーンアップ

ユーザーの発言：「停止または空のコンシューマーグループがないか確認してください」

アクション：

  1. すべてのコンシューマーグループを取得します
  2. コミット済みオフセットがあるグループのうち、Dead または Empty 状態のものを絞り込みます
  3. 安全にクリーンアップできる古いグループを報告します 結果：削除候補のグループ一覧

トラブルシューティング

コンシューマーグループの一覧が空です

原因：環境にコンシューマーグループが存在しないか、権限が制限されています。 解決策：コンシューマーが実行中であることを確認します。Lenses エージェントにコンシューマーグループの一覧表示権限があることを確認します。

ラグの数値が正しくないようです

原因：コンシューマーが最近停止した場合、コンシューマーグループのオフセットが古い可能性があります。 解決策：get_topic_partitions で取得したパーティションの終了オフセットとラグを比較します。オフセットが最後にコミットされた日時を確認します。

execute_sql がデータを返しません

原因：トピックが空か、クエリ対象の期間より古いメッセージしかありません。 解決策：get_dataset_message_metrics を使用して、トピックに最近のスループットがあるか確認します。ラグがあるコンシューマーがいるにもかかわらずトピックが空の場合は、プロデューサーに問題があることを示しています。

出力形式

## Consumer Lag Report

### Environment: {name}

### Critical (immediate action)
| Consumer Group | Topic | Total Lag | State | Diagnosis | Remediation |
|---------------|-------|-----------|-------|-----------|-------------|
| group-name | topic | 50000 | Stable | Throughput bottleneck | Scale consumers |

### Warning (investigate)
| Consumer Group | Topic | Total Lag | State | Diagnosis | Remediation |
|---------------|-------|-----------|-------|-----------|-------------|

### Suggestion (optimise)
| Consumer Group | Topic | Total Lag | State | Diagnosis | Remediation |
|---------------|-------|-----------|-------|-----------|-------------|

### Summary
- X consumer groups analysed
- Y groups with critical lag
- Z groups with warnings
- Stale/empty groups: N

コメント

Markdown 対応