メインコンテンツへスキップ
メインコンテンツへスキップ

Node.js

ClickStack は、テレメトリデータ（ログ、メトリクス、 トレース、例外）を収集するために OpenTelemetry の標準を使用します。トレースは自動インストルメンテーションによって生成されるため、 トレースから価値を得るために手動でインストルメンテーションを行う必要はありません。

このガイドでは次の内容を統合します:

  • ログ
  • メトリクス
  • トレース
  • 例外

はじめに​

HyperDX OpenTelemetry インストルメンテーションパッケージのインストール​

以下のコマンドを使用して、ClickStack OpenTelemetry パッケージ をインストールします。

npm install @hyperdx/node-opentelemetry

SDK の初期化​

SDK を初期化するには、アプリケーションのエントリポイントの先頭で init 関数を呼び出す必要があります。

const HyperDX = require('@hyperdx/node-opentelemetry');

HyperDX.init({
    apiKey: 'YOUR_INGESTION_API_KEY',
    service: 'my-service'
});

これにより、Node.js アプリケーションからトレース、メトリクス、ログが自動的に収集されます。

ログ収集のセットアップ​

デフォルトでは、console.* ログが収集されます。winston や pino などのロガーを使用している場合は、ログを ClickStack に送信するためのトランスポートをロガーに追加する必要があります。別の種類のロガーを使用している場合は、 お問い合わせいただくか、該当する場合は Kubernetes などのプラットフォームインテグレーションを確認してください。

ロガーとして winston を使用している場合は、次のトランスポートをロガーに追加する必要があります。

    import winston from 'winston';
    import * as HyperDX from '@hyperdx/node-opentelemetry';

    const logger = winston.createLogger({
      level: 'info',
      format: winston.format.json(),
      transports: [
        new winston.transports.Console(),
        HyperDX.getWinstonTransport('info', { // info 以上のログを送信
          detectResources: true,
        }),
      ],
    });

    export default logger;

エラー収集のセットアップ​

ClickStack SDK を使用すると、アプリケーション内で捕捉されていない例外やエラーを、スタックトレースおよびコードコンテキストとともに自動的に収集できます。

これを有効にするには、アプリケーションのエラー処理ミドルウェアの末尾に次のコードを追加するか、recordException 関数を使用して例外を手動で記録します。

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    apiKey: 'YOUR_INGESTION_API_KEY',
    service: 'my-service'
});
const app = express();

// ここにルートなどを追加します

// すべてのルートを追加した後、
// 他のエラー処理ミドルウェアが定義される前にこれを追加します
HyperDX.setupExpressErrorHandler(app);

app.listen(3000);

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

SDK で問題が発生している場合は、OTEL_LOG_LEVEL 環境変数を debug に設定することで詳細なログ出力を有効化できます。

export OTEL_LOG_LEVEL=debug

高度な計装設定​

コンソールログのキャプチャ​

デフォルトでは、ClickStack SDK はコンソールログをキャプチャします。これを無効にするには、 HDX_NODE_CONSOLE_CAPTURE 環境変数を 0 に設定してください。

export HDX_NODE_CONSOLE_CAPTURE=0

ユーザー情報やメタデータを付与する​

特定の属性や識別子（例: ユーザー ID やメールアドレス）に関連するすべてのイベントに簡単にタグ付けするには、setTraceAttributes 関数を呼び出します。この関数は、呼び出し以降の現在のトレースに関連するすべてのログやスパンに、指定した属性をタグとして付与します。この関数は、特定のリクエスト/トレース内で可能な限り早いタイミング（例: Express のミドルウェアスタックの先頭付近）で呼び出すことを推奨します。

これにより、識別子を自分で手動でタグ付けおよび伝播させる必要がなくなり、後から検索するために必要な識別子が、すべてのログやスパンに自動的にタグ付けされるようになります。

userId、userEmail、userName、teamName は、対応する値を Sessions UI に表示するために利用されますが、必須ではありません。その他の任意の追加値も指定可能であり、イベント検索に利用できます。

import * as HyperDX from '@hyperdx/node-opentelemetry';

app.use((req, res, next) => {
  // リクエストからユーザー情報を取得...

  // 現在のトレースにユーザー情報をアタッチ
  HyperDX.setTraceAttributes({
    userId,
    userEmail,
  });

  next();
});

トレース属性を有効にするには、HDX_NODE_BETA_MODE 環境変数を 1 に設定するか、init 関数に betaMode: true を渡してベータモードを有効にしてください。

export HDX_NODE_BETA_MODE=1

Google Cloud Run​

アプリケーションを Google Cloud Run 上で実行している場合、Cloud Trace は 受信リクエストに対して自動的にサンプリングヘッダーを付与し、 各インスタンスごとに 1 秒あたり 0.1 リクエストのみが トレースとしてサンプリングされるように制限します。

@hyperdx/node-opentelemetry パッケージは、デフォルトでサンプルレートを 1.0 に上書きします。

この挙動を変更したい場合、あるいは他の OpenTelemetry のインストール環境を 構成したい場合は、環境変数 OTEL_TRACES_SAMPLER=parentbased_always_on と OTEL_TRACES_SAMPLER_ARG=1 を手動で設定することで、同じ結果を得ることができます。

詳細や特定のリクエストに対してトレースを強制する方法については、 Google Cloud Run ドキュメント を参照してください。

自動インストルメント対象ライブラリ​

次のライブラリは、SDK によって自動的にインストルメント（トレース）されます。

別のインストール方法​

ClickStack OpenTelemetry CLI を使用してアプリケーションを実行する​

別の方法として、opentelemetry-instrument CLI を使用するか、Node.js の --require フラグを利用することで、コードを変更せずにアプリケーションを自動インストルメンテーションできます。CLI を使用すると、自動インストルメンテーションに対応した、より幅広いライブラリやフレームワークを利用できます。

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_NAME>' npx opentelemetry-instrument index.js

OTEL_SERVICE_NAME 環境変数は HyperDX アプリ内でサービスを識別するために使用されます。任意の名前を指定できます。

例外キャプチャの有効化​

未処理の例外キャプチャを有効にするには、環境変数 HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE を 1 に設定してください。

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

その後、Express や Koa で発生した例外を自動的に収集したり、例外を手動で捕捉したりするには、上記の Setup Error Collection セクションの手順に従ってください。

自動インストルメントされるライブラリ​

上記のインストール方法により、次のライブラリが自動的にインストルメント（トレース）されます：