ClickStack による Nginx ログのモニタリング

要約

このガイドでは、OpenTelemetry collector を構成して Nginx のアクセスログをインジェストし、ClickStack で Nginx をモニタリングする方法を説明します。以下のことを行います:

Nginx を JSON 形式のログを出力するように設定する
ログのインジェスト用にカスタム OTel collector 設定を作成する
カスタム設定を使用して ClickStack をデプロイする
あらかじめ用意されたダッシュボードを使って Nginx のメトリクスを可視化する

本番環境の Nginx を設定する前に連携をテストしたい場合は、サンプルログを含むデモデータセットを利用できます。

所要時間: 5〜10 分

既存の Nginx との統合

このセクションでは、ClickStack の OTel collector の設定を変更し、既存の Nginx 環境から ClickStack にログを送信するように構成する方法について説明します。既存環境を設定する前に統合の動作を試してみたい場合は、次のセクションにある事前構成済みの環境とサンプルデータを使用してテストできます。

前提条件

稼働中の ClickStack インスタンス
既存の Nginx 環境
Nginx 設定ファイルを編集可能な権限

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をリロードしてください。

カスタム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 と pipeline だけを定義します
memory_limiter、transform、batch の各 processor と clickhouse exporter は、ベースとなる ClickStack の設定ですでに定義されているため、名前を指定するだけで参照できます
time_parser オペレーターは、元のログの時刻情報を保持するために、Nginx の time_local フィールドからタイムスタンプを抽出します
パイプラインは、既存のprocessorを経由して、receiverからのデータをClickHouse exporterにルーティングします

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

既存のClickStackデプロイメントでカスタムコレクター設定を有効にするには、次の手順を実行してください:

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

オプション1: Docker Compose

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

services:
  clickstack:
    # ... existing configuration ...
    environment:
      - CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml
      # ... other environment variables ...
    volumes:
      - ./nginx-monitoring.yaml:/etc/otelcol-contrib/custom.config.yaml:ro
      - /var/log/nginx:/var/log/nginx:ro
      # ... other volumes ...

オプション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コレクターがnginxログファイルを読み取るための適切な権限を持っていることを確認してください。本番環境では、読み取り専用マウント（:ro）を使用し、最小権限の原則に従ってください。

HyperDXでのログの確認

設定完了後、HyperDXにログインし、ログが正常に送信されていることを確認してください：

検索ビューに移動します
ソースを Logs に設定し、request、request_time、upstream_response_time などのフィールドを含むログエントリが表示されていることを確認します。

以下のような表示が確認できます：

デモ用データセット

本番環境を構成する前に nginx 連携をテストしたいユーザー向けに、現実的なトラフィックパターンを持つ、あらかじめ生成された nginx アクセスログのサンプルデータセットを提供します。

サンプルデータセットのダウンロード

# ログをダウンロード
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/access.log

このデータセットには次の内容が含まれます：

現実的なトラフィックパターンを持つログエントリ
さまざまなエンドポイントと HTTP メソッド
成功したリクエストとエラーの混在
現実的なレスポンスタイムとバイト数

テスト用 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

デモ設定で 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

HyperDX でログを確認する

ClickStack が起動したら、次を実行します：

HyperDX を開き、自分のアカウントでログインします（まだアカウントがない場合は、まずアカウントを作成してください）
Search ビューに移動し、source を Logs に設定します
タイムレンジを 2025-10-19 11:00:00 - 2025-10-22 11:00:00 に設定します

Search ビューでは次のような表示になるはずです：

タイムゾーン表示

HyperDX はタイムスタンプをブラウザのローカルタイムゾーンで表示します。デモデータは 2025-10-20 11:00:00 - 2025-10-21 11:00:00 UTC の期間をカバーしています。広めのタイムレンジを指定することで、どの地域からでもデモ用ログが表示されるようにしています。ログが表示されたら、可視化を分かりやすくするために、タイムレンジを 24 時間に絞り込むことができます。

ダッシュボードと可視化

ClickStack で nginx の監視を始めやすくするために、Nginx Logs 用の基本的な可視化ダッシュボードを用意しています。

ダッシュボード構成をダウンロードする

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

HyperDX を開き、「Dashboards」セクションに移動します。
右上の三点リーダー（…）アイコンから「Import Dashboard」をクリックします。

nginx-logs-dashboard.json ファイルをアップロードし、「Finish Import」をクリックします。

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

注記

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

トラブルシューティング

カスタム構成が読み込まれない

環境変数 CUSTOM_OTELCOL_CONFIG_FILE が正しく設定されているか確認する

docker exec <コンテナ名> 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

コレクターがログを読み取れていることを確認する

docker exec `<container>` cat /var/log/nginx/access.log

実際の有効な構成に filelog レシーバーが含まれていることを確認する

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

コレクターのログにエラーがないか確認する

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

次のステップ

さらに分析を進めたい場合は、ダッシュボードを使って次のようなことを試してみてください。

重要なメトリクス（エラーレート、レイテンシのしきい値）に対するアラートを設定する
特定のユースケース向け（API モニタリング、セキュリティイベントなど）に追加のダッシュボードを作成する

既存の Nginx との統合​

前提条件​

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

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

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

オプション1: Docker Compose​

オプション2：Docker Run（オールインワンイメージ）​

HyperDXでのログの確認​

デモ用データセット​

サンプルデータセットのダウンロード​

テスト用 Collector 設定の作成​

デモ設定で ClickStack を実行する​

HyperDX でログを確認する​

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

ダッシュボード構成をダウンロードする​

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

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

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

カスタム構成が読み込まれない​

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

次のステップ​