ClickStack で Kafka メトリクスを監視する

ClickStack で Kafka メトリクスを監視する

要点

OTel JMX Metric Gatherer を使用して、ClickStack で Apache Kafka のパフォーマンスメトリクスを監視します。デモデータセットとあらかじめ用意されたダッシュボードも含まれています。

​

既存の Kafka デプロイメントとのインテグレーション

OpenTelemetry JMX Metric Gatherer コンテナーを実行してメトリクスを収集し、OTLP 経由で ClickStack に送信することで、既存の Kafka デプロイメントを監視できます。

既存のセットアップを変更せずにまずこのインテグレーションを試したい場合は、デモデータセットのセクションに進んでください。

前提条件

• 稼働中の ClickStack インスタンス
• JMX が有効な既存の Kafka 環境 (バージョン 2.0 以降)
• ClickStack と Kafka 間のネットワーク接続 (JMX ポート 9999、Kafka ポート 9092)
• OpenTelemetry JMX Metric Gatherer JAR (ダウンロード手順は以下)

1. ​

   ClickStack API key を取得する

   JMX Metric Gatherer はデータを ClickStack の OTLP エンドポイントに送信します。このエンドポイントでは認証が必要です。

   1. ClickStack の URL (例: http://localhost:8080) で HyperDX を開きます
   2. 必要に応じてアカウントを作成するか、ログインします
   3. Team Settings → API Keys に移動します
   4. インジェスト API key をコピーします

   5. これを環境変数として設定します:

   export CLICKSTACK_API_KEY=your-api-key-here
   
2. ​

   OpenTelemetry JMX Metric Gatherer をダウンロードする

   JMX Metric Gatherer の JAR をダウンロードします:

   curl -L -o opentelemetry-jmx-metrics.jar \
     https://github.com/open-telemetry/opentelemetry-java-contrib/releases/download/v1.32.0/opentelemetry-jmx-metrics.jar
   
3. ​

   Kafka JMX が有効であることを確認する

   Kafka ブローカーで JMX が有効になっていることを確認してください。Docker デプロイメントの場合:

   services:
     kafka:
       image: confluentinc/cp-kafka:latest
       environment:
         JMX_PORT: 9999
         KAFKA_JMX_HOSTNAME: kafka
         # ... その他のKafka設定
       ports:
         - "9092:9092"
         - "9999:9999"
   

   Dockerを使用しない環境でデプロイする場合は、Kafka の起動時に以下を設定してください:

   export JMX_PORT=9999
   

   JMX にアクセスできることを確認します:

   netstat -an | grep 9999
   
4. ​

   Docker Compose で JMX Metric Gatherer をデプロイする

   この例では、Kafka、JMX Metric Gatherer、ClickStack を含む一連の構成をまとめて示します。サービス名とエンドポイントは、既存のデプロイメントに合わせて調整してください。

   services:
     clickstack:
       image: clickhouse/clickstack-all-in-one:latest
       ports:
         - "8080:8080"
         - "4317:4317"
         - "4318:4318"
       networks:
         - monitoring
   
     kafka:
       image: confluentinc/cp-kafka:latest
       hostname: kafka
       container_name: kafka
       environment:
         KAFKA_NODE_ID: 1
         KAFKA_LISTENER_SECURITY_PROTOCOL_MAP: 'CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT'
         KAFKA_ADVERTISED_LISTENERS: 'PLAINTEXT://kafka:9092'
         KAFKA_PROCESS_ROLES: 'broker,controller'
         KAFKA_CONTROLLER_QUORUM_VOTERS: '1@kafka:29093'
         KAFKA_LISTENERS: 'PLAINTEXT://kafka:9092,CONTROLLER://kafka:29093'
         KAFKA_CONTROLLER_LISTENER_NAMES: 'CONTROLLER'
         KAFKA_LOG_DIRS: '/tmp/kraft-combined-logs'
         KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: 1
         KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: 1
         KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: 1
         CLUSTER_ID: 'MkU3OEVBNTcwNTJENDM2Qk'
         JMX_PORT: 9999
         KAFKA_JMX_HOSTNAME: kafka
         KAFKA_JMX_OPTS: '-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -Djava.rmi.server.hostname=kafka -Dcom.sun.management.jmxremote.rmi.port=9999'
       ports:
         - "9092:9092"
         - "9999:9999"
       networks:
         - monitoring
   
     kafka-jmx-exporter:
       image: eclipse-temurin:11-jre
       depends_on:
         - kafka
         - clickstack
       environment:
         - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
       volumes:
         - ./opentelemetry-jmx-metrics.jar:/app/opentelemetry-jmx-metrics.jar
       command: >
         sh -c "java
         -Dotel.jmx.service.url=service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi
         -Dotel.jmx.target.system=kafka
         -Dotel.metrics.exporter=otlp
         -Dotel.exporter.otlp.protocol=http/protobuf
         -Dotel.exporter.otlp.endpoint=http://clickstack:4318
         -Dotel.exporter.otlp.headers=authorization=\${CLICKSTACK_API_KEY}
         -Dotel.resource.attributes=service.name=kafka,kafka.broker.id=broker-0
         -Dotel.jmx.interval.milliseconds=10000
         -jar /app/opentelemetry-jmx-metrics.jar"
       networks:
         - monitoring
   
   networks:
     monitoring:
       driver: bridge
   

   主な設定パラメータ:

   • service:jmx:rmi:///jndi/rmi://kafka:9999/jmxrmi - JMX 接続 URL (Kafka のホスト名を使用)
   • otel.jmx.target.system=kafka - Kafka 固有のメトリクスを有効にします
   • http://clickstack:4318 - OTLP HTTP エンドポイント (ClickStack のホスト名を使用)
   • authorization=\${CLICKSTACK_API_KEY} - 認証用の API key (必須)
   • service.name=kafka,kafka.broker.id=broker-0 - フィルタリング用の resource 属性
   • 10000 - 収集間隔 (ミリ秒単位、10 秒)
5. ​

   HyperDX でメトリクスを確認する

   HyperDX にログインし、メトリクスが送信されていることを確認します。

   1. Chart Explorer に移動します
   2. kafka.message.count または kafka.partition.count を検索します
   3. メトリクスが 10 秒間隔で表示されるはずです

   確認すべき主要なメトリクス:

   • kafka.message.count - 処理されたメッセージの総数
   • kafka.partition.count - パーティションの総数
   • kafka.partition.under_replicated - 正常なクラスターでは 0 になるはずです
   • kafka.network.io - ネットワークのスループット
   • kafka.request.time.* - リクエストレイテンシのパーセンタイル

   アクティビティを発生させて、さらに多くのメトリクスを表示するには:

   # テストトピックを作成する
   docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"
   
   # テストメッセージを送信する
   echo -e "Message 1\nMessage 2\nMessage 3" | docker exec -i kafka bash -c "unset JMX_PORT && kafka-console-producer --topic test-topic --bootstrap-server kafka:9092"
   

   Kafka コンテナー内で Kafka クライアントコマンド (kafka-topics、kafka-console-producer など) を実行する場合は、JMX ポートの競合を避けるため、先頭に unset JMX_PORT && を付けてください。

​

デモデータセット

本番システムを構成する前に Kafka Metrics インテグレーションを試したい方向けに、実際に近い Kafka メトリクスのパターンを含む事前生成済みのデータセットを用意しています。

1. ​

   サンプルのメトリクスデータセットをダウンロードする

   事前生成済みのメトリクスファイルをダウンロードします (実際に近いパターンを含む 29 時間分の Kafka メトリクス) :

   # Gauge メトリクスをダウンロード（パーティション数、キューサイズ、レイテンシ、コンシューマラグ）
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-gauge.csv
   
   # sum メトリクスをダウンロード（メッセージレート、バイトレート、リクエスト数）
   curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/kafka-metrics-sum.csv
   

   このデータセットには、単一ブローカーの e コマース向け Kafka クラスターを想定した現実的なパターンが含まれています:

   • 06:00-08:00: 朝の増加 - 夜間のベースラインからトラフィックが急増
   • 10:00-10:15: フラッシュセール - 通常時の 3.5 倍までトラフィックが急増
   • 11:30: デプロイメントイベント - レプリケーション不足のパーティションの発生とともに、コンシューマラグが 12 倍に急増
   • 14:00-15:30: 買い物のピーク - ベースラインの 2.8 倍の高トラフィックが継続
   • 17:00-17:30: 退勤後の増加 - 2 回目のトラフィックピーク
   • 18:45: コンシューマのリバランス - リバランス中にラグが 6 倍に急増
   • 20:00-22:00: 夜間の減少 - 夜間レベルまで急激に低下
2. ​

   ClickStack を起動する

   ClickStack インスタンスを起動します:

   docker run -d --name clickstack-demo \
     -p 8080:8080 -p 4317:4317 -p 4318:4318 \
     clickhouse/clickstack-all-in-one:latest
   
3. ​

   ClickStack にメトリクスを読み込む

   メトリクスを ClickHouse に直接読み込みます:

   # Gauge メトリクスを読み込む（パーティション数、キューサイズ、レイテンシ、コンシューマラグ）
   cat kafka-metrics-gauge.csv | docker exec -i clickstack-demo \
     clickhouse-client --query "INSERT INTO otel_metrics_gauge FORMAT CSVWithNames"
   
   # sum メトリクスを読み込む（メッセージレート、バイトレート、リクエスト数）
   cat kafka-metrics-sum.csv | docker exec -i clickstack-demo \
     clickhouse-client --query "INSERT INTO otel_metrics_sum FORMAT CSVWithNames"
   
4. ​

   HyperDX でメトリクスを確認する

   読み込み後、メトリクスをすばやく確認するには、あらかじめ用意されたダッシュボードを使うのが最も簡単です。

   ダッシュボードをインポートして Kafka メトリクス全体をまとめて表示するには、ダッシュボードと可視化 セクションに進んでください。

   タイムゾーン表示

   HyperDX はタイムスタンプをブラウザーのローカルタイムゾーンで表示します。デモデータの期間は 2025-11-05 16:00:00 - 2025-11-06 16:00:00 (UTC) です。どの地域からでもデモメトリクスを確実に表示できるよう、時間範囲を 2025-11-04 16:00:00 - 2025-11-07 16:00:00 に設定してください。メトリクスが表示されたら、より見やすくするために範囲を 24 時間に絞り込めます。

​

ダッシュボードと可視化

ClickStack で Kafka の監視を始める際に役立つよう、Kafka メトリクス用の基本的な可視化を用意しています。

1. ​

   ダッシュボード設定ファイル

2. ​

   あらかじめ用意されたダッシュボードをインポートする

   1. HyperDX を開き、Dashboards セクションに移動します
   2. 右上の三点リーダー内にある Import Dashboard をクリックします

   3. kafka-metrics-dashboard.json ファイルをアップロードし、Finish Import をクリックします
3. ​

   ダッシュボードを表示する

   ダッシュボードが作成され、すべての可視化があらかじめ設定された状態で表示されます。

   デモデータセットを使用する場合は、時間範囲を 2025-11-05 16:00:00 - 2025-11-06 16:00:00 (UTC) に設定してください (ローカルのタイムゾーンに応じて調整してください) 。インポートしたダッシュボードには、デフォルトでは時間範囲が設定されていません。

​

トラブルシューティング

​

HyperDX にメトリクスが表示されない

APIキーが設定され、コンテナに渡されていることを確認してください:

# 環境変数を確認する
echo $CLICKSTACK_API_KEY

# コンテナー内に存在するか確認する
docker exec <jmx-exporter-container> env | grep CLICKSTACK_API_KEY

未設定の場合は、設定して再起動します:

export CLICKSTACK_API_KEY=your-api-key-here
docker compose up -d kafka-jmx-exporter

メトリクスがClickHouseに届いているか確認する：

docker exec <clickstack-container> clickhouse-client --query "
SELECT DISTINCT MetricName 
FROM otel_metrics_sum 
WHERE ServiceName = 'kafka' 
LIMIT 10
"

結果が表示されない場合は、JMX エクスポーターのログを確認してください:

docker compose logs kafka-jmx-exporter | grep -i "error\|connection" | tail -10

メトリクスにデータを入れるために、Kafka のアクティビティを発生させます:

# テストトピックを作成する
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# テストメッセージを送信する
echo -e "Message 1\nMessage 2\nMessage 3" | docker exec -i kafka bash -c "unset JMX_PORT && kafka-console-producer --topic test-topic --bootstrap-server kafka:9092"

​

認証エラー

Authorization failed または 401 Unauthorized が表示された場合:

1. HyperDX UI で API key を確認します (Settings → API Keys → Ingestion API Key)
2. エクスポートし直して再起動します:

export CLICKSTACK_API_KEY=your-correct-api-key
docker compose down
docker compose up -d

​

Kafka クライアントコマンドでのポート競合

Kafka コンテナー内で Kafka コマンドを実行すると、次のメッセージが表示されることがあります。

Error: Port already in use: 9999

コマンドの先頭に unset JMX_PORT && を付けてください:

docker exec kafka bash -c "unset JMX_PORT && kafka-topics --list --bootstrap-server kafka:9092"

​

ネットワーク接続の問題

JMX エクスポーターのログに Connection refused と表示される場合:

すべてのコンテナーが同じ Docker ネットワークに接続されていることを確認します:

docker compose ps
docker network inspect <network-name>

接続を確認します:

# JMX エクスポーターから ClickStack へ
docker exec <jmx-exporter-container> sh -c "timeout 2 bash -c 'cat < /dev/null > /dev/tcp/clickstack/4318' && echo 'Connected' || echo 'Failed'"

​

次のステップ

• 重要なメトリクス (レプリケーション数が不足しているパーティション、コンシューマラグの増加、リクエストレイテンシの急上昇) に対するalertsを設定します
• 特定のユースケース向けに追加のダッシュボードを作成します (トピックごとのスループット、コンシューマグループの監視)
• 一意のkafka.broker.id resource attributeを持つJMX Metric Gathererインスタンスを追加して、複数のKafkaブローカーを監視します

​

本番環境への移行

このガイドでは、JMX Metric Gatherer から ClickStack の OTLPエンドポイントへメトリクスを直接送信します。これは、テストや小規模なデプロイメントには適しています。

本番環境では、独自の OpenTelemetry Collector を agent としてデプロイし、JMX Exporter からメトリクスを受信して ClickStack に転送してください。これにより、バッチ処理、耐障害性、一元的な設定管理が可能になります。

本番環境向けのデプロイメントパターンや collector の設定例については、OpenTelemetry による取り込みを参照してください。