Contents
Kafka Consumer Lag の基礎と主要メトリクス
Kafka のコンシューマーラグは、コンシューマーが最新のオフセットに追いついていないメッセージ件数 を示す重要な指標です。
ラグが大きくなるとデータ処理遅延やバックプレッシャーが発生し、システム全体のスループット低下につながります。本節では、監視対象として必ず把握しておきたいメトリクスを整理し、その数式例と単位を併せて解説します。
consumer_lag と records_lag_max の意味
- consumer_lag
- コンシューマーグループごとに
latest offset − committed offsetを集計した値です。 -
単位は「メッセージ件数」。たとえば、パーティション 0 の latest = 12,500、committed = 11,800 の場合、
consumer_lag = 700 件となります。 -
records_lag_max
- 各パーティションで観測された records‑lag（未取得レコード数） の最大値を示します。
- 数式は
records_lag_max = max(records‑lag_i)（i は対象パーティション）。単位もメッセージ件数です。スパイクが発生したときに即座に検知できる点が特徴です。
これら二つのメトリクスを組み合わせて 総ラグ（全パーティション合計）と 最大瞬間ラグ を可視化すれば、システム全体像とボトルネックが一目で分かります。
JMX Exporter / kafka‑exporter と Prometheus による lag メトリクス取得
Kafka の内部統計は JMX 経由で提供されますが、そのままでは Prometheus から直接取得できません。JMX Exporter または Confluent kafka-exporter を介してメトリクスをエクスポートし、Prometheus がスクレイプする構成が一般的です。
Docker イメージと設定例
| コンポーネント | 推奨 Docker イメージ（バージョン固定） | 主な設定ファイル |
|---|---|---|
| JMX Exporter | prom/jmx-exporter:0.18.0 |
jmx_exporter.yml（Kafka の consumer fetch metrics を対象） |
| kafka‑exporter (Confluent) | confluentinc/cp-kafka-exporter:7.5.0 |
環境変数 KAFKA_EXPORTER_PROMETHEUS_JMX_HOST, KAFKA_EXPORTER_GROUP_IDS など |
※ バージョンを固定することで、将来の非互換リスク（latest タグ使用時の破壊的変更）を回避できます。
jmx_exporter.yml（抜粋）
|
1 2 3 4 5 6 7 8 9 |
startDelaySeconds: 0 hostPort: localhost:5556 rules: - pattern: kafka.consumer<type=consumer-fetch-manager-metrics, client-id=(.+)><>records-lag-max name: kafka_consumer_records_lag_max type: GAUGE labels: client_id: "$1" |
docker‑compose の例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
version: "3.8" services: kafka: image: confluentinc/cp-kafka:7.5.0 environment: KAFKA_ADVERTISED_LISTENERS: PLAINTEXT://kafka:9092 ports: - "9092:9092" jmx-exporter: image: prom/jmx-exporter:0.18.0 # 固定バージョン使用 volumes: - ./jmx_exporter.yml:/etc/jmx_exporter/config.yml command: ["-config.file=/etc/jmx_exporter/config.yml"] ports: - "5556:5556" |
Prometheus のスクレイプ設定とラベル付け
Prometheus 側では、上記 exporter が提供するエンドポイントを対象にジョブを定義します。group.id, topic, partition といったラベルは後続の Grafana クエリで粒度別集計に必須です。
|
1 2 3 4 5 6 7 8 9 |
scrape_configs: - job_name: "kafka-jmx-exporter" static_configs: - targets: ["jmx-exporter:5556"] relabel_configs: # exporter が付与する client_id を group ラベルへ変換 - source_labels: [client_id] target_label: group |
kafka_consumer_group_lag{group="my-group", topic="orders", partition="0"} のようにラベルが付与されるため、Grafana で topic 別 や partition 別 にフィルタリングできます。
AWS Managed Grafana へのデータソース登録とテンプレートダッシュボードのインポート
AWS が提供する Managed Grafana はフルマネージドな Grafana 環境で、IAM 認証や VPC エンドポイントを利用した安全な接続が可能です。公式ソリューションは Kafka 用に最適化されたテンプレートダッシュボードを提供しています。
言語統一の注記
- 本稿中の外部リンクは 日本語版 の URL を使用しています（例:
https://docs.aws.amazon.com/ja_jp/grafana/...）。 - 英語版をご希望の場合は、URL の
ja_jp部分をen_usに置き換えてください。 - どちらの言語ページでも内容は同一ですが、表記や日付形式に差異がある点だけご留意ください。
Prometheus データソース登録手順
- AWS コンソールの Amazon Managed Grafana で対象ワークスペースを開く
- 左メニュー → Data sources → Add data source を選択
- Prometheus を選び、以下を入力
- URL:
https://<workspace-id>.prometheus.aws.amazon.com（VPC エンドポイントの場合はプライベート DNS） - Authentication provider: AWS Signature Version 4（IAM ロールに
AmazonPrometheusReadOnlyAccessを付与） - Save & test で接続確認が成功すれば完了
公式ソリューションテンプレートのインポートとカスタマイズポイント
- AWS のドキュメント（AWS Managed Grafana で Kafka アプリケーションをモニタリング）に記載された手順で、Dashboard → Import からテンプレート JSON を貼り付けます。
- インポート後の主なカスタマイズポイントは以下です。
| カスタマイズ項目 | 内容 |
|---|---|
| データソース名 | ワークスペース固有の名前に変更（例: Prometheus_Kafka） |
| ラベル名統一 | JMX Exporter が出す client_id を Grafana 変数で利用しやすいよう group にリネーム |
| パネル配置 | Consumer Lag (Total) と Lag by Topic を上部に集約し、下部に Records Lag Max を配置すると全体と瞬間スパイクが見やすくなる |
Red Hat が提供する AMQ Streams 用テンプレート（Red Hat AMQ Streams のメトリクスおよびダッシュボード設定）と比較すると、ラベル命名規則が若干異なる点に注意してください。必要に応じて Grafana の変数 でエイリアスを付与し、一貫した UI を実現します。
実践的なカスタムパネルとアラート設定
テンプレートだけでは自社の SLA に合わせた監視が難しい場合があります。ここでは PromQL クエリ例 と可視化タイプ、さらに Grafana アラート の作り方を示します。
クエリ例と可視化タイプ
| パネル目的 | PromQL クエリ | 推奨可視化 |
|---|---|---|
| Total Lag（全コンシューマー合計） | sum(kafka_consumer_group_lag) by (group) |
Stat（単一数値） |
| Topic 別 Lag | sum(kafka_consumer_group_lag{topic=~".+"}) by (topic) |
Bar gauge（横棒で比較） |
| Partition 別 Lag | kafka_consumer_group_lag{group="$group", topic="$topic"} |
Time series（時系列折れ線） |
| Lag 増加率（5 分間の変化） | rate(kafka_consumer_group_lag[5m]) |
Time series（色分けで上昇傾向を強調） |
ポイント：Grafana の Explore 画面でクエリを試し、期待通りのラベルが出力されることを必ず確認してください。
推奨アラートルールと閾値
Grafana アラートは Prometheus アラート規則 と同等に扱えます。以下は一般的な運用で採用されている例です（組織のトラフィックに合わせて調整してください）。
|
1 2 3 4 5 6 7 8 9 |
alert: KafkaConsumerLagHigh expr: sum(kafka_consumer_group_lag) by (group) > 10000 for: 5m labels: severity: critical annotations: summary: "Kafka コンシューマー {{ $labels.group }} のラグが 10,000 件を超えています" description: "{{ $labels.group }} の lag が 5 分間連続で閾値を超えているため、処理遅延が発生する恐れがあります。" |
Grafana UI では Alerting → Create alert rule → 上記クエリと for: 5m を設定し、通知チャネル（メール、Slack 等）へ連携します。
ダッシュボードの検証・デバッグとトラブルシューティングフロー
作成したパネルやアラートが正しく機能するかは、Prometheus の query_editor と Grafana の Explore で確認します。問題が発生した際の典型的な手順をまとめました。
Prometheus query_editor と Grafana Explore の活用
- Prometheus UI → Graph タブで
kafka_consumer_group_lag{group="my-group"}を実行し、ラベルと値が期待通りか確認 - Grafana → Explore でデータソースを Prometheus に切替え、同じクエリを入力して結果のタイムスタンプや欠損が無いかチェック
- パネル単位で Inspect → Query を開き、実際に送信された PromQL とレスポンスサンプルを比較
ラグ急増時の対処策
| 原因 | 確認ポイント | 推奨アクション |
|---|---|---|
| コンシューマースレッド不足 | consumer_threads メトリクスや JVM スレッド数 |
スレッドプールを拡張し、max.poll.records を調整 |
| パーティション再割り当て遅延 | 特定パーティションの lag が突出しているか (kafka_consumer_group_lag{partition="X"}) |
手動で rebalance を実行、または partition.assignment.strategy を変更 |
| バックエンド（DB/外部 API）処理遅延 | アプリ側ログや外部システムのレスポンス時間 | ボトルネックを特定し、スロットリングやキャッシュ導入 |
| メトリクス取得設定ミス | exporter の jmx_exporter.yml で対象 MBean が抜けているか |
設定ファイルを再確認し、必要な MBean（例: records-lag-max）を追加 |
上記フローは Grafana のパネル でリアルタイムにラグ変化を観測しながら実施すると、原因特定のスピードが向上します。
本稿でカバーしたポイント
- Kafka Consumer Lag の概念と
consumer_lag・records_lag_maxの数式例・単位 - JMX Exporter と Confluent kafka‑exporter を Docker で構築し、バージョン固定で非互換リスクを回避する方法
- AWS Managed Grafana への Prometheus データソース登録手順と、外部リンクの言語統一に関する注記
- 実務で使えるカスタムパネル（総ラグ、トピック別、パーティション別、増加率）と具体的な PromQL クエリ例
- 推奨アラートルール（lag > 10,000 件が 5 分間継続）と設定手順
- ダッシュボードの検証・デバッグ方法、そしてラグ急増時のトラブルシューティングフロー
これらを踏まえて、まずは AWS Managed Grafana のテンプレートダッシュボードをインポートし、自社環境の Prometheus エンドポイントに接続して動作確認してください。その後、カスタムパネルやアラートを追加すれば、Kafka コンシューマーラグをリアルタイムで可視化・監視できる実践的なダッシュボードが完成します。