ClickStackでKafkaログを監視

既存のKafkaとのインテグレーション

このセクションでは、ClickStack OTel collector の設定を変更し、既存の Kafka 環境から Kafka ブローカーのログを ClickStack に送信するよう設定する方法を説明します。既存環境の設定を行う前に Kafkaログインテグレーションを試したい場合は、"デモデータセット" セクションにある事前設定済みの環境とサンプルデータでテストできます。

前提条件

稼働中の ClickStack インスタンス
既存の Kafka インストール環境 (バージョン 2.0 以降)
Kafka のログファイル (server.log、controller.log など) へのアクセス

Kafka のログ設定を確認する

Kafka は Log4j を使用しており、ログは kafka.logs.dir システムプロパティまたは LOG_DIR 環境変数で指定されたディレクトリに書き込まれます。ログファイルの保存場所を確認してください。

# Default locations
ls $KAFKA_HOME/logs/      # Standard Apache Kafka (defaults to <install-dir>/logs/)
ls /var/log/kafka/        # RPM/DEB package installations

主な Kafka のログファイル:

server.log: 一般的なブローカーのログ (起動、接続、レプリケーション、エラー)
controller.log: コントローラー固有のイベント (リーダー選出、パーティションの再割り当て)
state-change.log: パーティションおよびレプリカの状態遷移

Kafka のデフォルトの Log4j パターンでは、次のような行が出力されます:

[2026-03-09 14:23:45,123] INFO [KafkaServer id=0] started (kafka.server.KafkaServer)

Kafka 用のカスタム OTel collector 設定を作成する

ClickStack では、カスタム設定ファイルをマウントし、環境変数を設定することで、ベースの OpenTelemetry Collector 設定を拡張できます。このカスタム設定は、HyperDX が OpAMP 経由で管理するベース設定にマージされます。

以下の内容で、kafka-logs-monitoring.yaml という名前のファイルを作成します。

receivers:
  filelog/kafka:
    include:
      - /var/log/kafka/server.log
      - /var/log/kafka/controller.log  # optional, only exists if log4j is configured with separate file appenders
      - /var/log/kafka/state-change.log  # optional, same as above
    start_at: beginning
    multiline:
      line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
    operators:
      - type: regex_parser
        regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.timestamp
          layout: '%Y-%m-%d %H:%M:%S,%L'
        severity:
          parse_from: attributes.severity

      - type: move
        from: attributes.message
        to: body

      - type: add
        field: attributes.source
        value: "kafka"

      - type: add
        field: resource["service.name"]
        value: "kafka-production"

service:
  pipelines:
    logs/kafka:
      receivers: [filelog/kafka]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse

ClickStack でカスタム設定を読み込むように構成する

既存の ClickStack デプロイメントでカスタム collector の設定を有効にするには、次の対応が必要です。

カスタム設定ファイルを /etc/otelcol-contrib/custom.config.yaml にマウントする
環境変数 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml を設定する
collector が Kafka のログを読み取れるように、Kafka のログディレクトリをマウントする

ClickStack のデプロイメント設定を更新します。

services:
  clickstack:
    # ... 既存の設定 ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... その他の環境変数 ...
    volumes:
      - ./kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/kafka:/var/log/kafka:ro
      # ... その他のボリューム ...

Docker で all-in-one イメージを使用している場合は、次を実行します。

docker run --name clickstack \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/kafka-logs-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/kafka:/var/log/kafka:ro \
  clickhouse/clickstack-all-in-one:latest

HyperDX でログを確認する

設定が完了したら、HyperDX にログインし、ログが取り込まれていることを確認します。

デモデータセット

本番環境のシステムを設定する前に、事前に生成されたサンプルデータセットを使って Kafkaログインテグレーションをテストします。

サンプルデータセットをダウンロードする

サンプルのログファイルをダウンロードします。

curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/kafka/server.log

テスト用の collector 設定を作成する

以下の内容で、kafka-logs-demo.yaml という名前のファイルを作成します。

cat > kafka-logs-demo.yaml << 'EOF'
receivers:
  filelog/kafka:
    include:
      - /tmp/kafka-demo/server.log
    start_at: beginning
    multiline:
      line_start_pattern: '^\[\d{4}-\d{2}-\d{2}'
    operators:
      - type: regex_parser
        regex: '^\[(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3})\] (?P<severity>\w+) (?P<message>.*)'
        parse_from: body
        parse_to: attributes
        timestamp:
          parse_from: attributes.timestamp
          layout: '%Y-%m-%d %H:%M:%S,%L'
        severity:
          parse_from: attributes.severity

      - type: move
        from: attributes.message
        to: body

      - type: add
        field: attributes.source
        value: "kafka-demo"

      - type: add
        field: resource["service.name"]
        value: "kafka-demo"

service:
  pipelines:
    logs/kafka-demo:
      receivers: [filelog/kafka]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
EOF

デモ設定で ClickStack を実行する

デモ用のログと設定を使用して ClickStack を実行します。

docker run --name clickstack-demo \
  -p 8080:8080 -p 4317:4317 -p 4318:4318 \
  -e CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml \
  -v "$(pwd)/kafka-logs-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/server.log:/tmp/kafka-demo/server.log:ro" \
  clickhouse/clickstack-all-in-one:latest

HyperDX でログを確認する

ClickStack が起動したら、次の手順を実行します。

HyperDX を開いてアカウントにログインします (先にアカウントの作成が必要な場合があります)
Search view に移動し、ログソースを Logs に設定します
時間範囲を 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC) が含まれるように設定します

ダッシュボードと可視化

ダッシュボード設定をダウンロード

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

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

HyperDX を開き、Dashboards セクションに移動します。
右上の三点メニューから「Import Dashboard」をクリックします。

kafka-logs-dashboard.json ファイルをアップロードし、インポートを完了します。

ダッシュボードが作成され、すべての可視化が事前設定された状態になります

デモデータセットでは、時間範囲に 2026-03-09 00:00:00 - 2026-03-10 00:00:00 (UTC) が含まれるよう設定します。

トラブルシューティング

実際に適用されているconfigに、filelog receiverが含まれていることを確認します。

docker exec <container> cat /etc/otel/supervisor-data/effective.yaml | grep -A 10 filelog

collector のエラーを確認する:

docker exec <container> cat /etc/otel/supervisor-data/agent.log

Kafka のログ形式が想定どおりのパターンに一致していることを確認します。

tail -1 /var/log/kafka/server.log

Kafka のインストールでカスタムの Log4j パターンを使用している場合は、regex_parser の正規表現もそれに合わせて調整してください。

次のステップ

重要なイベント (ブローカー障害、レプリケーションエラー、コンシューマグループの問題) に備えてアラートを設定します
包括的な Kafka 監視のためにKafka メトリクスと組み合わせます
特定のユースケース (コントローライベント、パーティション再割り当て) 向けに追加のダッシュボードを作成します

本番環境への移行

このガイドでは、素早くセットアップできるよう、ClickStack に組み込まれた OpenTelemetry Collector を利用しています。本番環境へのデプロイでは、独自の OTel Collector を実行し、データを ClickStack の OTLP エンドポイントに送信することを推奨します。本番環境向けの構成については、OpenTelemetry データの送信を参照してください。