ClickStack による Nginx トレースの監視

Nginx にトレーシングを追加する最も簡単な方法は、OpenTelemetry サポートが組み込まれた公式の Nginx イメージを使用することです。

nginx:otel イメージを使用する

現在の Nginx イメージを OpenTelemetry 対応版に置き換えます。

# docker-compose.yml または Dockerfile 内
image: nginx:1.27-otel

このイメージには ngx_otel_module.so があらかじめインストールされており、すぐに使用できます。

nginx.conf ファイルに OpenTelemetry の設定を追加します。この設定では、モジュールを読み込み、トレースを ClickStack の OTLP エンドポイントに送信します。

まず、API key を取得します:

1. ClickStack の URL で HyperDX を開きます
2. Settings → API Keys に移動します
3. インジェスト API key をコピーします
4. 環境変数として設定します: export CLICKSTACK_API_KEY=your-api-key-here

これを nginx.conf に追加します:

load_module modules/ngx_otel_module.so;

events {
    worker_connections 1024;
}

http {
    # OpenTelemetry エクスポーターの設定
    otel_exporter {
        endpoint <clickstack-host>:4317;
        header authorization ${CLICKSTACK_API_KEY};
    }
    
    # この nginx インスタンスを識別するためのサービス名
    otel_service_name "nginx-proxy";
    
    # トレーシングを有効化
    otel_trace on;
    
    server {
        listen 80;
        
        location / {
            # この location でトレーシングを有効化
            otel_trace_context propagate;
            otel_span_name "$request_method $uri";
            
            # トレースにリクエストの詳細を追加
            otel_span_attr http.status_code $status;
            otel_span_attr http.request.method $request_method;
            otel_span_attr http.route $uri;
            
            # 既存のプロキシまたはアプリケーション設定
            proxy_pass http://your-backend;
        }
    }
}

Docker で Nginx を実行している場合は、環境変数をコンテナーに渡します:

services:
  nginx:
    image: nginx:1.27-otel
    environment:
      - CLICKSTACK_API_KEY=${CLICKSTACK_API_KEY}
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

<clickstack-host> は、ClickStack インスタンスのホスト名または IP アドレスに置き換えてください。

設定内容を理解する

トレースされる内容: Nginx への各リクエストごとに、次を示す trace スパン が作成されます:

• リクエストメソッドとパス
• HTTP ステータスコード
• リクエスト時間
• タイムスタンプ

スパン 属性: otel_span_attr ディレクティブは各トレースにメタデータを追加し、ステータスコード、メソッド、ルートなどで HyperDX 内のリクエストを絞り込んで分析できるようにします。

これらの変更を行った後、Nginx の設定をテストします:

nginx -t

テストに成功したら、Nginx を再読み込みします:

# Docker の場合
docker-compose restart nginx

# systemd の場合
sudo systemctl reload nginx

設定が完了したら、HyperDX にログインしてトレースが流れていることを確認します。次のような表示になるはずです。トレースが表示されない場合は、時間範囲を調整してみてください。

まだ ClickStack を起動していない場合は、次のコマンドを実行します。

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

続行する前に、ClickStack の初期化が完了するまで約 30 秒待ってください。

• ポート 8080: HyperDX の Web インターフェイス
• ポート 4317: OTLP gRPC エンドポイント (nginx モジュールで使用)
• ポート 4318: OTLP HTTP エンドポイント (デモトレースで使用)

サンプルトレースファイルをダウンロードし、タイムスタンプ を現在時刻に更新します。

# トレースをダウンロード
curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nginx-traces-sample.json

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

• 現実的なタイミングの 1,000 件のトレーススパン
• 異なるトラフィックパターンを持つ 9 種類の エンドポイント
• 約 93% の成功 (200) 、約 3% のクライアントエラー (404) 、約 4% のサーバーエラー (500)
• 10ms 〜 800ms のレイテンシ
• 元のトラフィックパターンを維持したまま、現在時刻にシフト

API key を環境変数として設定します (まだ設定していない場合) 。

export CLICKSTACK_API_KEY=your-api-key-here

API key を取得するには:

1. ClickStack の URL で HyperDX を開きます
2. Settings → API Keys に移動します
3. インジェスト API key をコピーします

続いて、トレースを ClickStack に送信します。

curl -X POST http://localhost:4318/v1/traces \
  -H "Content-Type: application/json" \
  -H "Authorization: $CLICKSTACK_API_KEY" \
  -d @nginx-traces-sample.json

トレースが正常に送信されたことを示す {"partialSuccess":{}} のようなレスポンスが返るはずです。1,000 件すべてのトレースが ClickStack に取り込まれます。

1. HyperDX を開いてアカウントにログインします (先にアカウントの作成が必要な場合があります)
2. Search view に移動し、source を Traces に設定します
3. 時間範囲を 2025-10-25 13:00:00 - 2025-10-28 13:00:00 に設定します

Search view には次のように表示されるはずです。

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

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

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