Set up docs MCP既存の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 エクスポーターにルーティングします
#### ClickStack でカスタム設定を読み込むように構成する
既存の ClickStack デプロイメントでカスタム collector の設定を有効にするには、以下を行う必要があります。
- カスタム設定ファイルを /etc/otelcol-contrib/custom.config.yaml にマウントする
- 環境変数 CUSTOM_OTELCOL_CONFIG_FILE=/etc/otelcol-contrib/custom.config.yaml を設定する
- collector が読み取れるように、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:latestHyperDXでログを確認する
設定が完了したら、HyperDX にログインし、ログが取り込まれていることを確認します。
- Search view に移動します
- ログソースを 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:latestHyperDX でログを確認する
ClickStack が起動したら、次の手順を実行します。
- HyperDX を開いてアカウントにログインします (先にアカウントの作成が必要な場合があります)
- Search view に移動し、ログソースを
Logsに設定します - 時間範囲を 2025-10-19 11:00:00 - 2025-10-22 11:00:00 に設定します
Search view には次のように表示されるはずです。
ダッシュボードと可視化
ClickStack で nginx の監視をすぐに開始できるよう、Nginx ログ用の基本的な可視化を用意しています。
ダッシュボード設定をダウンロードする
あらかじめ用意されたダッシュボードをインポートする
- HyperDX を開き、Dashboards セクションに移動します。
- 右上の三点メニューから「Import Dashboard」をクリックします。
- nginx-logs-dashboard.json ファイルをアップロードし、「finish import」をクリックします。
事前設定済みの可視化を含むダッシュボードが作成されます
トラブルシューティング
カスタム設定が読み込まれない
- 環境変数 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.yamlHyperDX にログが表示されない場合
- 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次のステップ
本番環境への移行
このガイドでは、手早くセットアップできるよう、ClickStack に組み込まれている OpenTelemetry Collector を拡張して使用します。本番環境にデプロイする場合は、独自の OTel collector を実行し、データを ClickStack の OTLP エンドポイントに送信することをお勧めします。本番環境向けの構成については、OpenTelemetry データの送信を参照してください。