要点OpenTelemetry の自動インストルメンテーションを使用して、Node.js アプリケーションの分散トレースを ClickStack に取り込みます。デモデータセットとあらかじめ用意されたダッシュボードも含まれています。
既存の Node.js アプリケーションとのインテグレーション
前提条件
- OTLP エンドポイントにアクセス可能な状態で稼働している ClickStack インスタンス (ポート 4317/4318)
- 既存の Node.js アプリケーション (Node.js 14 以上)
- npm または yarn パッケージマネージャー
- ClickStack のホスト名または IP アドレス
OpenTelemetry をインストールして設定する
@hyperdx/node-opentelemetry パッケージをインストールし、アプリケーションの起動時に初期化します。インストール手順の詳細は、Node.js SDK ガイドを参照してください。ClickStack API key を取得する
ClickStack の OTLP エンドポイントにトレースを送信するための API key です。
- ClickStack の URL (例: http://localhost:8080) で HyperDX を開きます
- 必要に応じてアカウントを作成するか、ログインします
- Team Settings → API Keys に移動します
- インジェスト API key をコピーします
アプリケーションを実行する
環境変数を設定して Node.js アプリケーションを起動します。export CLICKSTACK_API_KEY=your-api-key-here
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
トラフィックを生成する
アプリケーションにリクエストを送信してトレースを生成します。# 単純なリクエスト
curl http://localhost:3000/
curl http://localhost:3000/api/users
curl http://localhost:3000/api/products
# 負荷をシミュレートする
for i in {1..100}; do curl -s http://localhost:3000/ > /dev/null; done
HyperDX でトレースを確認する
設定が完了したら、HyperDX にログインしてトレースが流れていることを確認します。次のように表示されるはずです。トレースが表示されない場合は、時間範囲を調整してみてください。任意のトレースをクリックすると、span、タイミング、属性を含む詳細ビューを確認できます。サンプルデータセットをダウンロードする
サンプルトレースファイルをダウンロードします。curl -O https://datasets-documentation.s3.eu-west-3.amazonaws.com/clickstack-integrations/nodejs/nodejs-traces-sample.json
ClickStack を起動する
まだ ClickStack を起動していない場合は、次のコマンドで起動します。docker run -d --name clickstack-demo \
-p 8080:8080 -p 4317:4317 -p 4318:4318 \
-e CLICKHOUSE_USER=default \
-e CLICKHOUSE_PASSWORD= \
clickhouse/clickstack-all-in-one:latest
ClickStack API key を取得する
トレースを ClickStack の OTLP エンドポイントに送信するには、API key が必要です。
- ClickStack の URL (例: http://localhost:8080) で HyperDX を開きます
- 必要に応じてアカウントを作成するか、ログインします
- Team Settings → API Keys に移動します
- インジェスト API key をコピーします
API key を環境変数として設定します。export CLICKSTACK_API_KEY=your-api-key-here
トレースを ClickStack に送信する
curl -X POST http://localhost:4318/v1/traces \
-H "Content-Type: application/json" \
-H "Authorization: $CLICKSTACK_API_KEY" \
-d @nodejs-traces-sample.json
{"partialSuccess":{}} のようなレスポンスが返されるはずです。HyperDX でトレースを確認する
- HyperDX を開いてアカウントにログインします (先にアカウントの作成が必要な場合があります)
- Search ビューに移動し、ソースを Traces に設定します
- 時間範囲を 2025-10-25 13:00:00 - 2025-10-28 13:00:00 に設定します
タイムゾーン表示HyperDX では、タイムスタンプはブラウザーのローカルタイムゾーンで表示されます。デモデータの期間は 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) です。時間範囲を広めに設定しているため、どこからアクセスしてもデモトレースを確認できます。トレースが表示されたら、より見やすく可視化するために、範囲を 24 時間に絞り込めます。
あらかじめ用意されたダッシュボードをインポートする
- HyperDX を開き、Dashboards セクションに移動します
- 右上の Import Dashboard をクリックします (省略記号メニュー内)
nodejs-traces-dashboard.json ファイルをアップロードし、Finish Import をクリックします
すべての可視化が事前設定された状態でダッシュボードが作成されます
デモデータセットを使用する場合は、時間範囲を 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) に設定してください (ローカルのタイムゾーンに応じて調整してください) 。インポートしたダッシュボードには、デフォルトでは時間範囲が設定されていません。
curl -X POST http://localhost:4318/v1/traces \
-H "Content-Type: application/json" \
-H "Authorization: $CLICKSTACK_API_KEY" \
-d @nodejs-traces-sample.json
echo $CLICKSTACK_API_KEY
# API キーが出力されます
echo $OTEL_EXPORTER_OTLP_ENDPOINT
# http://localhost:4318 またはご利用の ClickStack ホストが出力されます
curl -v http://localhost:4318/v1/traces
- 重要なメトリクス (エラー率、レイテンシのしきい値) に対するalertsを設定します
- 特定のユースケース (API の監視、セキュリティイベント) 向けに追加のダッシュボードを作成します
このガイドでは、トレースを ClickStack の OTLP エンドポイントへ直接送信する HyperDX SDK を使用します。これは、開発、テスト、小規模～中規模の本番環境での運用に適しています。
より大規模な本番環境で運用する場合や、テレメトリーデータをより細かく制御する必要がある場合は、独自の OpenTelemetry Collector をエージェントとしてデプロイすることを検討してください。
本番環境向けのデプロイパターンや collector の設定例については、OpenTelemetry で取り込む を参照してください。
