Node.js

ClickStack は、テレメトリーデータ (ログ、メトリクス、トレース、例外) の収集に OpenTelemetry 標準を採用しています。トレースは自動インストルメンテーションによって生成されるため、トレーシングを活用するうえで手動のインストルメンテーションは必要ありません。

はじめに

HyperDX OpenTelemetry インストルメンテーションパッケージをインストールする

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

NPM
Yarn

npm install @hyperdx/node-opentelemetry

yarn add @hyperdx/node-opentelemetry

SDK の初期化

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

require
import

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

HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    apiKey: '<YOUR_INGESTION_API_KEY>', // Managed ClickStack の場合は省略
    service: 'my-service'
});

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

HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    apiKey: '<YOUR_INGESTION_API_KEY>', // Managed ClickStack の場合は省略
    service: 'my-service'
});

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

ログ収集の設定

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

Winston
Pino
console.log

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;

pino をロガーとして使用している場合は、以下のトランスポートをロガーに追加し、ログとトレースを相関付けるために mixin を指定する必要があります。

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

const logger = pino(
    pino.transport({
    mixin: HyperDX.getPinoMixinFunction,
    targets: [
        HyperDX.getPinoTransport('info', { // info 以上のログを送信
        detectResources: true,
        }),
    ],
    }),
);

export default logger;

デフォルトでは、console.* メソッドはそのままでサポートされています。追加の設定は不要です。これは、HDX_NODE_CONSOLE_CAPTURE 環境変数を 0 に設定するか、init 関数に consoleCapture: false を渡すことで無効にできます。

エラー収集の設定

ClickStack SDK は、アプリケーション内の未捕捉の例外やエラーを、完全なスタックトレースとコードコンテキスト付きで自動的に収集できます。これを有効にするには、アプリケーションのエラーハンドリングミドルウェアの最後に次のコードを追加するか、recordException 関数を使って例外を手動で記録します。

Express
Koa
手動

const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    apiKey: '<YOUR_INGESTION_API_KEY>', // Managed ClickStack の場合は省略
    service: 'my-service'
});
const app = express();

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

// これをすべてのルートの後に追加し、
// ほかのエラーハンドリングミドルウェアを定義する前に配置します
HyperDX.setupExpressErrorHandler(app);

app.listen(3000);

const Koa = require("koa");
const Router = require("@koa/router");
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: '<YOUR_OTEL_COLLECTOR_HTTP_ENDPOINT>',
    apiKey: '<YOUR_INGESTION_API_KEY>', // Managed ClickStack の場合は省略
    service: 'my-service'
});

const router = new Router();
const app = new Koa();

HyperDX.setupKoaErrorHandler(app);

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

app.listen(3030);

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

function myErrorHandler(error, req, res, next) {
    // これはアプリケーション内のどこからでも使用できます
    HyperDX.recordException(error);
}

トラブルシューティング

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

export OTEL_LOG_LEVEL=debug

高度なインストルメンテーションの設定

コンソールログの取得

デフォルトでは、ClickStack SDK はコンソールログを取得します。これを無効にするには、環境変数 HDX_NODE_CONSOLE_CAPTURE を 0 に設定します。

copy

export HDX_NODE_CONSOLE_CAPTURE=0

ユーザー情報またはメタデータを付加する

特定の属性や識別子 (例: user id または email) に関連するすべてのイベントへ簡単にタグ付けするには、setTraceAttributes 関数を呼び出します。これにより、呼び出し以降、現在の trace に関連付けられたすべてのログ/スパンに、指定した属性が付与されます。この関数は、対象の request/trace 内のできるだけ早い段階 (例: Express のミドルウェアスタックのできるだけ早い段階) で呼び出すことを推奨します。これは、後で検索できるように、すべてのログ/スパンに適切な識別子を自動的にタグ付けするための便利な方法です。識別子を自分で手動でタグ付けして伝播させる必要はありません。 userId、userEmail、userName、および teamName を指定すると、対応する値がセッション 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 は受信リクエストにサンプリング用ヘッダーを自動的に挿入します。現在は、各インスタンスでトレースのサンプリングが毎秒 0.1 リクエストに制限されています。 @hyperdx/node-opentelemetry パッケージは、デフォルトでサンプルレートを 1.0 に上書きします。この動作を変更したい場合や、他の OpenTelemetry インストールで同様に設定したい場合は、環境変数 OTEL_TRACES_SAMPLER=parentbased_always_on と OTEL_TRACES_SAMPLER_ARG=1 を手動で設定することで、同じ結果を得られます。詳細、および特定のリクエストでトレースを強制的に有効にする方法については、 Google Cloud Run documentation を参照してください。

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

以下のライブラリは、SDK によって自動的にインストルメントされ、トレースが収集されます。

代替のインストール方法

ClickStack OpenTelemetry CLI でアプリケーションを実行する

また、opentelemetry-instrument CLI や Node.js の --require フラグを使えば、コードを変更することなくアプリケーションを自動インストルメントできます。CLI をインストールすると、自動インストルメンテーションに対応するライブラリやフレームワークの対象がより広がります。

NPX を使用
カスタムエントリポイント（例: Nodemon、ts-node など）
コードのインポート

Managed ClickStackManaged ClickStack では HYPERDX_API_KEY は省略できます。

HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' npx opentelemetry-instrument index.js

Managed ClickStackManaged ClickStack では HYPERDX_API_KEY は省略できます。

HYPERDX_API_KEY='<YOUR_INGESTION_API_KEY>' OTEL_SERVICE_NAME='<YOUR_SERVICE_NAME>' ts-node -r '@hyperdx/node-opentelemetry/build/src/tracing' index.js

// アプリケーションで最初に読み込まれるファイルの先頭でこれをインポートします
// API key は引き続き `HYPERDX_API_KEY` 環境変数で指定します
import { initSDK } from '@hyperdx/node-opentelemetry';

initSDK({
    consoleCapture: true, // 任意、デフォルト: true
    additionalInstrumentations: [], // 任意、デフォルト: []
});

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

例外のキャプチャを有効にする

未処理の例外のキャプチャを有効にするには、HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE 環境変数を 1 に設定する必要があります。

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

その後、Express や Koa の例外を自動的に収集する場合、または例外を手動でキャッチする場合は、上記のエラー収集の設定セクションの手順に従ってください。

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

以下のライブラリは、上記のインストール方法を使用すると自動的にインストルメントされ (トレースされ) ます。

はじめる

機能

ClickStack の管理

ガイド

インテグレーションパートナー

はじめに

HyperDX OpenTelemetry インストルメンテーションパッケージをインストールする

SDK の初期化

ログ収集の設定

エラー収集の設定

トラブルシューティング

高度なインストルメンテーションの設定

コンソールログの取得

ユーザー情報またはメタデータを付加する

Google Cloud Run

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

代替のインストール方法

ClickStack OpenTelemetry CLI でアプリケーションを実行する

例外のキャプチャを有効にする

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

​はじめに

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

​SDK の初期化

​ログ収集の設定

​エラー収集の設定

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

​高度なインストルメンテーションの設定

​コンソールログの取得

​ユーザー情報またはメタデータを付加する

​Google Cloud Run

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

​代替のインストール方法

​ClickStack OpenTelemetry CLI でアプリケーションを実行する

​例外のキャプチャを有効にする

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

はじめに

HyperDX OpenTelemetry インストルメンテーションパッケージをインストールする

SDK の初期化

ログ収集の設定

エラー収集の設定

トラブルシューティング

高度なインストルメンテーションの設定

コンソールログの取得

ユーザー情報またはメタデータを付加する

Google Cloud Run

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

代替のインストール方法

ClickStack OpenTelemetry CLI でアプリケーションを実行する

例外のキャプチャを有効にする

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