メインコンテンツへスキップ
メインコンテンツへスキップ

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 エクスポーターに送信する
注記
  • カスタム設定では、新しいレシーバーとパイプラインだけを定義します
  • processors（memory_limiter、transform、batch）および exporters（clickhouse）は、すでにベースの ClickStack 構成で定義済みなので、名前を指定して参照するだけで済みます
  • time_parser オペレーターは、元のログのタイムスタンプを保持するために、Nginx の time_local フィールドからタイムスタンプを抽出します
  • パイプラインは、既存のprocessorsを介して、receiversからClickHouse exporterへデータをルーティングします

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

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

  1. カスタム設定ファイルを /etc/otelcol-contrib/custom.config.yaml にマウントします
  2. 環境変数 CUSTOM_OTELCOL_CONFIG_FILE に /etc/otelcol-contrib/custom.config.yaml を設定します
  3. コレクターが読み込めるように 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 \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest
注記

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

HyperDXでのログの確認​

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

  1. 検索ビューに移動します
  2. ソースを 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 メソッド
  • 成功したリクエストとエラーの混在
  • 実運用に近いレスポンスタイムとバイト数

テスト用コレクター設定を作成する​

次の設定内容で 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" \
  docker.hyperdx.io/hyperdx/hyperdx-all-in-one:latest

HyperDX でログを確認する​

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

  1. HyperDX を開き、アカウントにログインします（まだアカウントがない場合は作成してください）
  2. 検索ビューに移動し、ソースを Logs に設定します
  3. 時間範囲を 2025-10-19 11:00:00 - 2025-10-22 11:00:00 に設定します

検索ビューには、次のように表示されるはずです。

タイムゾーン表示

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

ログビュー
ログビュー

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

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

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

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

  1. HyperDX を開き、「Dashboards」セクションに移動します。
  2. 右上の三点リーダー（…）アイコンから「Import Dashboard」をクリックします。
ダッシュボードのインポート
  1. 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 モニタリング、セキュリティイベントなど）に追加のダッシュボードを作成する