メインコンテンツへスキップ
要点OTel の filelog receiver を使用して、Nginx のアクセスログ (JSON フォーマット) を ClickStack で収集し、可視化します。デモデータセットとあらかじめ用意されたダッシュボードが含まれています。

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

このセクションでは、ClickStack OTel collector の設定を変更し、既存の Nginx 環境から ClickStack にログを送信する方法を説明します。 既存環境の設定を行う前にこのインテグレーションを試したい場合は、次のセクションにある事前設定済みのセットアップとサンプルデータを使ってテストできます。
前提条件
  • ClickStack インスタンスが稼働していること
  • 既存の Nginx インストール環境
  • Nginx の設定ファイルを変更するためのアクセス権
1

​
Nginx のログフォーマットを設定する

まず、ログをパースしやすくするために、Nginx が JSON フォーマットでログを出力するよう設定します。このログフォーマット定義を nginx.conf に追加してください。nginx.conf ファイルは通常、次の場所にあります。
  • Linux (apt/yum): /etc/nginx/nginx.conf
  • macOS (Homebrew): /usr/local/etc/nginx/nginx.conf または /opt/homebrew/etc/nginx/nginx.conf
  • Docker: 設定は通常、ボリュームとしてマウントされます
このログフォーマット定義を http ブロックに追加してください。
http {
    log_format json_combined escape=json
    '{'
      '"time_local":"$time_local",'
      '"remote_addr":"$remote_addr",'
      '"request_method":"$request_method",'
      '"request_uri":"$request_uri",'
      '"status":$status,'
      '"body_bytes_sent":$body_bytes_sent,'
      '"request_time":$request_time,'
      '"upstream_response_time":"$upstream_response_time",'
      '"http_referer":"$http_referer",'
      '"http_user_agent":"$http_user_agent"'
    '}';

    access_log /var/log/nginx/access.log json_combined;
    error_log /var/log/nginx/error.log warn;
}
この変更を行った後、Nginx を再読み込みします。
2

​
カスタム OTel collector 設定を作成する

ClickStack では、カスタム設定ファイルをマウントし、環境変数を設定することで、ベースの OpenTelemetry Collector 設定を拡張できます。カスタム設定は、HyperDX が OpAMP 経由で管理するベース設定にマージされます。以下の内容で、nginx-monitoring.yaml という名前のファイルを作成します。
receivers:
  filelog:
    include:
      - /var/log/nginx/access.log
      - /var/log/nginx/error.log
    start_at: end 
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx"

service:
  pipelines:
    logs/nginx:
      receivers: [filelog]
      processors:
        - memory_limiter
        - transform
        - batch
      exporters:
        - clickhouse
この設定では、次のことを行います:
  • 標準的な場所にある Nginx のログを読み取ります
  • JSON 形式のログエントリを解析します
  • 元のログのタイムスタンプを抽出して保持します
  • HyperDX でのフィルタリング用に source: Nginx 属性を追加します
  • 専用のパイプラインを通じてログを ClickHouse エクスポーターにルーティングします
  • カスタム設定では、新しい receiver とパイプラインのみを定義します
  • プロセッサ (memory_limiter、transform、batch) とエクスポーター (clickhouse) は、ベースの ClickStack 設定ですでに定義されているため、ここでは名前で参照するだけです
  • time_parser operator は、Nginx の time_local フィールドからタイムスタンプを抽出し、元のログ時刻を保持します
  • パイプラインは、既存のプロセッサを介して、receiver から ClickHouse エクスポーターへデータをルーティングします
3

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

既存の ClickStack デプロイメントでカスタム collector の設定を有効にするには、以下を行う必要があります。
  1. カスタム設定ファイルを /etc/otelcol-contrib/custom.config.yaml にマウントする
  2. 環境変数 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml を設定する
  3. collector が読み取れるように、Nginx のログディレクトリをマウントする
オプション 1: Docker Compose
ClickStack のデプロイメント設定を更新します。
services:
  clickstack:
    # ... 既存の設定 ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... その他の環境変数 ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... その他のボリューム ...
オプション 2: Docker Run (オールインワンイメージ)
オールインワンイメージを docker run で使用する場合:
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)/nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v /var/log/nginx:/var/log/nginx:ro \
  clickhouse/clickstack-all-in-one:latest
ClickStack collector に、nginx のログファイルを読み取るための適切な権限があることを確認してください。本番環境では、読み取り専用マウント (:ro) を使用し、最小権限の原則に従ってください。
4

​
HyperDXでログを確認する

設定が完了したら、HyperDX にログインし、ログが取り込まれていることを確認します。
  1. Search view に移動します
  2. ログソースを Logs に設定し、request、request_time、upstream_response_time などのフィールドを持つログエントリが表示されていることを確認します
以下のように表示されれば正常です。

​
デモデータセット

本番環境を構成する前に nginx インテグレーションを試したいユーザー向けに、実際のトラフィックパターンに近い、事前生成済みの nginx アクセスログのサンプルデータセットを用意しています。
1

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

# ログをダウンロード
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log
このデータセットには、以下が含まれます。
  • 実際のトラフィックパターンに近いログエントリ
  • さまざまなエンドポイントと HTTP メソッド
  • 正常なリクエストとエラーが混在したデータ
  • 現実的なレスポンス時間とバイト数
2

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

以下の設定内容で、nginx-demo.yaml という名前のファイルを作成します。
cat > nginx-demo.yaml << 'EOF'
receivers:
  filelog:
    include:
      - /tmp/nginx-demo/access.log
    start_at: beginning  # デモデータ用に先頭から読み取る
    operators:
      - type: json_parser
        parse_from: body
        parse_to: attributes
      - type: time_parser
        parse_from: attributes.time_local
        layout: '%d/%b/%Y:%H:%M:%S %z'
      - type: add
        field: attributes.source
        value: "nginx-demo"

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

​
デモ設定で 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)/nginx-demo.yaml:/etc/otelcol-contrib/custom.config.yaml:ro" \
  -v "$(pwd)/access.log:/tmp/nginx-demo/access.log:ro" \
  clickhouse/clickstack-all-in-one:latest
4

​
HyperDX でログを確認する

ClickStack が起動したら、次の手順を実行します。
  1. HyperDX を開いてアカウントにログインします (先にアカウントの作成が必要な場合があります)
  2. Search view に移動し、ログソースを Logs に設定します
  3. 時間範囲を 2025-10-19 11:00:00 - 2025-10-22 11:00:00 に設定します
Search view には次のように表示されるはずです。
タイムゾーン表示HyperDX はタイムスタンプをブラウザーのローカルタイムゾーンで表示します。デモデータの対象期間は UTC の 2025-10-20 11:00:00 - 2025-10-21 11:00:00 です。時間範囲を広めに設定しているため、どの地域からでもデモログを確認できます。ログが表示されたら、より見やすく可視化するために、範囲を 24 時間に絞ることができます。

​
ダッシュボードと可視化

ClickStack で nginx の監視をすぐに開始できるよう、Nginx Logs 用の基本的な可視化を用意しています。
1

​
ダッシュボード設定をする

2

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

  1. HyperDX を開き、Dashboards セクションに移動します。
  2. 右上の三点メニューから「Import Dashboard」をクリックします。
  1. nginx-logs-dashboard.json ファイルをアップロードし、「finish import」をクリックします。
3

​
事前設定済みの可視化を含むダッシュボードが作成されます

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

​
トラブルシューティング

​
カスタム設定が読み込まれない

  • 環境変数 CUSTOM_OTELCOL_CONFIG_FILE が正しく設定されているか確認してください
docker exec <container-name> printenv CUSTOM_OTELCOL_CONFIG_FILE
  • カスタム設定ファイルが /etc/otelcol-contrib/custom.config.yaml にマウントされていることを確認します
docker exec <container-name> ls -lh /etc/otelcol-contrib/custom.config.yaml
  • カスタム設定の内容を表示し、問題なく読み取れることを確認します
docker exec <container-name> cat /etc/otelcol-contrib/custom.config.yaml

​
HyperDX にログが表示されない場合

  • nginx が JSON 形式でログを出力していることを確認してください
tail -f /var/log/nginx/access.log
  • collector がログを読み取れることを確認する
docker exec `<container>` cat /var/log/nginx/access.log
  • 有効な設定に filelog receiver が含まれていることを確認する
docker exec `<container>` cat /etc/otel/supervisor-data/effective.yaml | grep filelog
  • collector のログにエラーがないか確認する
docker exec `<container>` cat /etc/otel/supervisor-data/agent.log

​
次のステップ

  • 重要なメトリクス (エラー率、レイテンシのしきい値) についてアラートを設定します
  • 特定のユースケース (API の監視、セキュリティイベント) 向けに追加のダッシュボードを作成します

​
本番環境への移行

このガイドでは、すばやくセットアップできるよう、ClickStack に組み込まれている OpenTelemetry Collector を使用します。本番環境でデプロイする場合は、独自の OTel Collector を実行し、データを ClickStack の OTLP エンドポイントに送信することを推奨します。本番環境向けの構成については、OpenTelemetry データの送信を参照してください。
最終更新日 2026年6月10日