NicheeLab Kafka監視: Prometheus / Grafana 連携 — エクスポータ構成とダッシュボード

Kafka運用でまず外せないのは、ブローカの健全性とレプリカ状況の可視化です。本稿は、Prometheus + Grafanaを前提に、JMX Exporter/Node Exporterの構成と、試験でも頻出の代表メトリクスを軸にダッシュボードとアラートを設計する要点をまとめます。

内容はApache KafkaのJMXメトリクス仕様（公式ドキュメント）に沿い、バージョンに左右されにくい指標名と監視ロジックを採用します。受験（CCAAK）と実務の両方でそのまま使える構成を目指します。

監視アーキテクチャと役割分担

KafkaはJMXで豊富な内部メトリクスを公開します。これをPrometheusに取り込む最も一般的で安定した手段が、JMX Exporter（javaagent）です。ブローカ、Kafka Connect、Schema Registry、REST ProxyなどのJavaプロセスごとにjavaagentを付与し、HTTPでメトリクスを露出させます。OSレベルはNode Exporterで補完します。

PrometheusはPullモデルで各エンドポイントをスクレイプし、GrafanaはPromQLで可視化します。クラスタ/環境/ロールでラベル設計を統一しておくと、ダッシュボードの変数化とアラートの集計が安定します。

• JMX Exporter（javaagent）は各Kafka系プロセスに同居。デフォルトでHTTPのみ、TLSが必要ならリバースプロキシ等で終端。
• Node ExporterはOS共通のCPU/メモリ/ディスク/ネットワークを収集。KafkaのI/Oボトルネック把握に必須。
• ダッシュボードは「ブローカ健全性」「レプリカ健全性」「ネットワークI/O」「スレッド余力」を分けると運用判断が速い。

Kafka監視（Prometheus Pull）の全体像

監視対象エンドポイントのインベントリ例（論理名とURL）

# 環境: production, クラスタ: cluster-a
- job: kafka-broker
  targets:
    - broker-1.prod.example.com:7071
    - broker-2.prod.example.com:7071
    - broker-3.prod.example.com:7071
- job: kafka-connect
  targets:
    - connect-1.prod.example.com:7072
- job: node
  targets:
    - broker-1.prod.example.com:9100
    - broker-2.prod.example.com:9100
    - broker-3.prod.example.com:9100

JMX Exporter（javaagent）のセットアップ

Kafka系プロセスにjmx_prometheus_javaagent.jarを付与し、HTTPでメトリクスを露出します。Kafka Brokerであれば、KAFKA_OPTSや環境変数を用いて起動引数にjavaagentを追加します。公式のJMX名をルールで明示しておくと、PromQLが安定します。

最小構成ではUnderReplicatedPartitions、ActiveControllerCount、RequestHandlerAvgIdlePercent、Network I/O関連をまず収集します。ルールで余分な属性を落とし、高カーディナリティ（topic/partition単位）の爆発を避けます。

• ポート例: Broker 7071、Connect 7072。Node Exporterは9100を慣用。
• lowercaseOutputNameを有効化し、指標名はスネークケースに統一。
• topic/partitionを含む詳細メトリクスは後述のPrometheus側で集約用だけに残し、rawはドロップ可。

Kafka Brokerへのjavaagent付与とjmx_exporter設定例

# 1) Kafka起動にjavaagentを付与（systemdや環境変数で）
export KAFKA_OPTS="-javaagent:/opt/jmx/jmx_prometheus_javaagent.jar=7071:/opt/jmx/kafka-broker-jmx.yml $KAFKA_OPTS"

# 2) /opt/jmx/kafka-broker-jmx.yml（最小安定セット）
---
lowercaseOutputName: true
rules:
  # UnderReplicatedPartitions
  - pattern: 'kafka.server<type=ReplicaManager, name=UnderReplicatedPartitions>(Count)'
    name: kafka_server_replicamanager_underreplicatedpartitions
    type: GAUGE
    help: Number of under-replicated partitions
  # ActiveControllerCount（単一クラスタでは常に1が正）
  - pattern: 'kafka.controller<type=KafkaController, name=ActiveControllerCount>(Value)'
    name: kafka_controller_kafkacontroller_activecontrollercount
    type: GAUGE
  # RequestHandlerAvgIdlePercent（0〜1）
  - pattern: 'kafka.server<type=KafkaRequestHandlerPool, name=RequestHandlerAvgIdlePercent>(Value)'
    name: kafka_server_kafkarequesthandlerpool_requesthandleravgidlepercent
    type: GAUGE
  # Network I/O
  - pattern: 'kafka.server<type=BrokerTopicMetrics, name=BytesInPerSec, topic=.*>(OneMinuteRate|Count)'
    name: kafka_server_brokertopicmetrics_bytesinpersec_$1
    type: GAUGE
    labels:
      topic: "$topic"
  - pattern: 'kafka.server<type=BrokerTopicMetrics, name=BytesOutPerSec, topic=.*>(OneMinuteRate|Count)'
    name: kafka_server_brokertopicmetrics_bytesoutpersec_$1
    type: GAUGE
    labels:
      topic: "$topic"

Prometheusのスクレイプ設定とリラベル設計

Prometheusではジョブごとにtargetsを分離し、環境・クラスタ名をexternal_labelsに持たせます。メトリクス側の高カーディナリティ抑制はmetrics_relabel_configsで行います（例: topicは上位N件のみ許容、partitionラベルは原則ドロップ）。

レイテンシやスループット評価ではレート関数を使い、1m/5m/15mで複数の窓を使い分けるとノイズ耐性が上がります。

• external_labelsでcluster, envを固定付与。ダッシュボードの変数化とアラート抑止に効く。
• metrics_relabelでpartitionや任意topicをドロップ。大規模クラスタでは必須。
• tls_config/basic_authはプロキシ配下のときのみ。エクスポータ自体はHTTP運用が一般的。

prometheus.ymlの例（ジョブ分離と高カーディナリティ抑制）

global:
  scrape_interval: 15s
  evaluation_interval: 15s
  external_labels:
    env: production
    cluster: cluster-a

scrape_configs:
  - job_name: 'kafka-broker'
    static_configs:
      - targets: ['broker-1.prod.example.com:7071','broker-2.prod.example.com:7071','broker-3.prod.example.com:7071']
    metrics_relabel_configs:
      # partitionラベルを持つメトリクスは原則ドロップ
      - action: drop
        regex: .+
        source_labels: [partition]
      # topicは重要上位のみ残す例（^app- で始まるものだけ）
      - action: keep
        source_labels: [topic]
        regex: app-.*
      - action: labeldrop
        regex: (client_id|fetcher_id)

  - job_name: 'kafka-connect'
    static_configs:
      - targets: ['connect-1.prod.example.com:7072']

  - job_name: 'node'
    static_configs:
      - targets: ['broker-1.prod.example.com:9100','broker-2.prod.example.com:9100','broker-3.prod.example.com:9100']

Grafanaダッシュボード設計（必須パネルとPromQL）

CCAAK対策と実務の両面でまず用意したいのは、レプリカ健全性・コントローラ状態・ブローカ処理余力・I/Oの4系統です。以下は最小クエリ例です。変数: cluster, broker, topicなど。

単一グラフにすべてを載せず、アラート条件に直結する集約系（sum/max）と、ドリルダウン系（by broker/topic）の両方を用意すると故障切り分けが速くなります。

• UnderReplicatedPartitionsが>0で即時検知。応急処置はブローカ健全性とネットワーク確認。
• ActiveControllerCountはクラスタで常に1が正。≠1は障害兆候。
• RequestHandlerAvgIdlePercentは0.2未満が続けば飽和疑い。

代表パネルのPromQL例（ダッシュボードに貼る）

# 1) レプリカ健全性
sum(kafka_server_replicamanager_underreplicatedpartitions{cluster="$cluster"})

# 2) コントローラ状態（1で正常）
max(kafka_controller_kafkacontroller_activecontrollercount{cluster="$cluster"})

# 3) ブローカ処理余力（平均）
avg by (cluster) (
  kafka_server_kafkarequesthandlerpool_requesthandleravgidlepercent{cluster="$cluster"}
)

# 4) Bytes In/Out（トピック合計・5分移動平均）
rate(sum by (cluster) (kafka_server_brokertopicmetrics_bytesinpersec_oneminuterate{cluster="$cluster"}))[5m]
rate(sum by (cluster) (kafka_server_brokertopicmetrics_bytesoutpersec_oneminuterate{cluster="$cluster"}))[5m]

# 5) ブローカ別のUnderReplicatedPartitions（ドリルダウン）
max by (instance) (kafka_server_replicamanager_underreplicatedpartitions{cluster="$cluster"})

アラート設計（Prometheusルール）

過検知を避けるため、短期のスパイクは抑え、1〜5分のfor句を付与します。UnderReplicatedPartitionsは直ちに対応すべきため1m、RequestHandlerAvgIdlePercentは継続観測で5mを推奨。

通知はクラスタとブローカ単位のタグ付けでルーティングし、メッセージには調査の起点（対象ブローカ、直近の再割り当てや障害履歴）を含めます。

• UnderReplicatedPartitions > 0 を最優先で検知。
• ActiveControllerCount ≠ 1 はコントローラフェイルオーバ中。継続時のみ通知。
• RequestHandlerAvgIdlePercent < 0.2 が続けばスレッド/CPU飽和の疑い。

alerting rules（Prometheus）の例

groups:
- name: kafka.rules
  rules:
  - alert: KafkaUnderReplicatedPartitions
    expr: sum(kafka_server_replicamanager_underreplicatedpartitions) > 0
    for: 1m
    labels:
      severity: critical
      team: kafka
    annotations:
      summary: "Under-replicated partitions detected"
      description: "There are {{ $value }} under-replicated partitions in {{ $labels.cluster }}. Check broker health and network."

  - alert: KafkaControllerNotOne
    expr: max(kafka_controller_kafkacontroller_activecontrollercount) != 1
    for: 3m
    labels:
      severity: warning
      team: kafka
    annotations:
      summary: "ActiveControllerCount is not 1"
      description: "Active controller count is {{ $value }} in {{ $labels.cluster }} (expected 1). Investigate controller elections."

  - alert: KafkaRequestHandlersSaturated
    expr: avg(kafka_server_kafkarequesthandlerpool_requesthandleravgidlepercent) < 0.2
    for: 5m
    labels:
      severity: warning
      team: kafka
    annotations:
      summary: "Low RequestHandler idle percent"
      description: "Handler idle percent below 0.2 for 5m in {{ $labels.cluster }}. Consider scaling or tuning."

セキュリティと運用の落とし穴（TLS、マルチクラスタ、チューニング）

多くのエクスポータは平文HTTPのみです。ネットワーク境界内に限定するか、必要に応じてリバースプロキシでTLS/認証を終端します。Prometheus側はbasic_auth/tls_configを設定可能です。エンドポイントはネットワークACLで限定公開にしてください。

マルチクラスタ運用では、external_labelsでclusterを固定付与し、同一Prometheusで集約しても衝突しないようにします。高カーディナリティはmetrics_relabel_configsで計画的に削減し、ダッシュボードは変数で切替可能にします。

• Exportersは基本HTTP。必要ならプロキシでTLS終端＋Basic認証。
• external_labelsとjob分離でマルチクラスタを安全に集約。
• 収集負荷はscrape_interval/timeout/target数で管理。15s/1000 targets規模なら性能検証が必要。

Prometheusでプロキシ配下のエクスポータをスクレイプ（Basic認証/TLS）の例

scrape_configs:
  - job_name: 'kafka-broker-proxied'
    scheme: https
    basic_auth:
      username: prometheus
      password: ${EXPORTER_BASIC_AUTH_PASSWORD}
    tls_config:
      insecure_skip_verify: false
    static_configs:
      - targets: ['broker-1.proxy.example.com:443','broker-2.proxy.example.com:443']

問題で確認

よくある質問