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

要点OpenTelemetry の自動インストルメンテーションを使用して、Node.js アプリケーションの分散トレースを 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 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、タイミング、属性を含む詳細ビューを確認できます。

デモデータセット

本番アプリケーションをインストルメントする前に 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 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 時間に絞り込めます。

ダッシュボードと可視化

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

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

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

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

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

すべての可視化が事前設定された状態でダッシュボードが作成されます

デモデータセットを使用する場合は、時間範囲を 2025-10-26 13:00:00 - 2025-10-27 13:00:00 (UTC) に設定してください (ローカルのタイムゾーンに応じて調整してください) 。インポートしたダッシュボードには、デフォルトでは時間範囲が設定されていません。

トラブルシューティング

curl 経由でデモのトレースが表示されない

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

HyperDX にトレースが表示されない

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

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 で取り込むを参照してください。

​既存の Node.js アプリケーションとのインテグレーション

前提条件

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

​ClickStack API key を取得する

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

​トラフィックを生成する

​HyperDX でトレースを確認する

​デモデータセット

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

​ClickStack を起動する

​ClickStack API key を取得する

​トレースを ClickStack に送信する

​HyperDX でトレースを確認する

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

​ダッシュボード設定をする

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

​すべての可視化が事前設定された状態でダッシュボードが作成されます

​トラブルシューティング

​curl 経由でデモのトレースが表示されない

​HyperDX にトレースが表示されない

​次のステップ

​本番環境での運用

既存の Node.js アプリケーションとのインテグレーション

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

ClickStack API key を取得する

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

トラフィックを生成する

HyperDX でトレースを確認する

デモデータセット

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

ClickStack を起動する

ClickStack API key を取得する

トレースを ClickStack に送信する

HyperDX でトレースを確認する

ダッシュボードと可視化

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

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

すべての可視化が事前設定された状態でダッシュボードが作成されます

トラブルシューティング

curl 経由でデモのトレースが表示されない

HyperDX にトレースが表示されない

次のステップ

本番環境での運用