Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

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

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

ClickStack API key を取得する

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

  1. ClickStack の URL (例: http://localhost:8080) で HyperDX を開きます
  2. 必要に応じてアカウントを作成するか、ログインします
  3. Team Settings → API Keys に移動します
  4. インジェスト API key をコピーします
ClickStack API Key
  1. これを環境変数として設定します:
export CLICKSTACK_API_KEY=your-api-key-here

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

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

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

services:
  kafka:
    image: confluentinc/cp-kafka:latest
    environment:
      JMX_PORT: 9999
      KAFKA_JMX_HOSTNAME: kafka
      # ... other Kafka configuration
    ports:
      - "9092:9092"
      - "9999:9999"

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

export JMX_PORT=9999

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

netstat -an | grep 9999

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 秒)

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.* - リクエストレイテンシのパーセンタイル

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

# Create a test topic
docker exec kafka bash -c "unset JMX_PORT && kafka-topics --create --topic test-topic --bootstrap-server kafka:9092 --partitions 3 --replication-factor 1"

# Send test messages
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 メトリクスのパターンを含む事前生成済みのデータセットを用意しています。

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

事前生成済みのメトリクスファイルをダウンロードします (実際に近いパターンを含む 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: 夜間の減少 - 夜間レベルまで急激に低下

ClickStack を起動する

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

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

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"

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

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

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

ダッシュボードと可視化

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

ダッシュボード設定ファイルをダウンロード

ダッシュボード設定ファイルをダウンロード。

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

  1. HyperDX を開き、Dashboards セクションに移動します
  2. 右上の三点リーダー内にある Import Dashboard をクリックします
ダッシュボードのインポートボタン
  1. kafka-metrics-dashboard.json ファイルをアップロードし、Finish Import をクリックします
インポート完了ダイアログ

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

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

Kafka メトリクスダッシュボード

トラブルシューティング

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 をエージェントとしてデプロイし、JMX エクスポーター からメトリクスを受信して ClickStack に転送してください。これにより、バッチ処理、耐障害性、一元的な設定管理が可能になります。

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

Navigation