ClickStackでNode.jsのトレースを監視

このセクションでは、OpenTelemetry の自動インストルメンテーションを使用して、既存の Node.js アプリケーションに分散トレーシングを追加する方法を説明します。

既存環境の構成を行う前にこのインテグレーションを試したい場合は、あらかじめ構成済みの環境とサンプルデータを使って、デモデータセットのセクションで試すことができます。

• OTLP エンドポイントにアクセス可能な状態で稼働している ClickStack インスタンス (ポート 4317/4318)
• 既存の Node.js アプリケーション (Node.js 14 以上)
• npm または yarn パッケージマネージャー
• ClickStack のホスト名または IP アドレス

OpenTelemetry をインストールして設定する

@hyperdx/node-opentelemetry パッケージをインストールし、アプリケーションの起動時に初期化します。インストール手順の詳細は、Node.js SDK ガイドを参照してください。

ClickStack API キー を取得する

ClickStack の OTLP エンドポイントにトレースを送信するための API キー です。

1. ClickStack の URL (例: http://localhost:8080) で HyperDX を開きます
2. 必要に応じてアカウントを作成するか、ログインします
3. Team Settings → API Keys に移動します
4. インジェスト API キー をコピーします

アプリケーションを実行する

環境変数を設定して 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、タイミング、属性を含む詳細ビューを確認できます。

本番アプリケーションをインストルメントする前に ClickStack で Node.js のトレーシングを試したいユーザー向けに、実際のトラフィックパターンに近い、事前生成済みの Node.js アプリケーショントレースのサンプルデータセットを提供しています。

サンプルデータセットをダウンロードする

サンプルトレースファイルをダウンロードします。

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 キー を取得する

トレースを ClickStack の OTLP エンドポイントに送信するには、API キー が必要です。

1. ClickStack の URL (例: http://localhost:8080) で HyperDX を開きます
2. 必要に応じてアカウントを作成するか、ログインします
3. Team Settings → API Keys に移動します
4. インジェスト API キー をコピーします

API キー を環境変数として設定します。

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 でトレースを確認する

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

Node.js アプリケーションのパフォーマンス監視をすぐに始められるよう、主要なトレースの可視化を含むあらかじめ用意されたダッシュボードを提供しています。

ダッシュボード設定をダウンロードする

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

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

1. HyperDX を開き、Dashboards セクションに移動します
2. 右上の Import Dashboard をクリックします (省略記号メニュー内)

3. nodejs-traces-dashboard.json ファイルをアップロードし、Finish Import をクリックします

すべての可視化があらかじめ設定された状態でダッシュボードが作成されます

curl でトレースを送信しても HyperDX に表示されない場合は、もう一度トレースを送信してみてください。

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

これは、curl を使ったデモ方式で発生する既知の問題であり、インストルメントされた本番環境のアプリケーションには影響しません。

環境変数が設定されていることを確認してください：

echo $CLICKSTACK_API_KEY
# API キーが出力されます

echo $OTEL_EXPORTER_OTLP_ENDPOINT
# http://localhost:4318 またはご利用の ClickStack ホストが出力されます

ネットワーク接続を確認する:

curl -v http://localhost:4318/v1/traces

OTLP エンドポイントに正常に接続できるはずです。

アプリケーションログを確認してください: アプリの起動時に OpenTelemetry の初期化メッセージが出力されているか確認してください。HyperDX SDK から、初期化が完了したことを示すメッセージが出力されるはずです。

• 重要なメトリクス (エラー率、レイテンシのしきい値) に対するalertsを設定します
• 特定のユースケース (API の監視、セキュリティイベント) 向けに追加のダッシュボードを作成します

このガイドでは、トレースを ClickStack の OTLPエンドポイントに直接送信する HyperDX SDK を使用します。これは、開発、テスト、および小規模から中規模の本番環境へのデプロイに適しています。 より大規模な本番環境で運用する場合や、テレメトリーデータをより細かく制御する必要がある場合は、独自の OpenTelemetry Collector をエージェントとしてデプロイすることを検討してください。 本番環境向けのデプロイパターンと collector の設定例については、OpenTelemetry を使用した取り込みを参照してください。