Node.js

ClickStack 用 Node.js SDK - The ClickHouse Observability Stack

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

このガイドでは、以下を統合します:

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

​

はじめに

​

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

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

NPM

npm install @hyperdx/node-opentelemetry 

Yarn

yarn add @hyperdx/node-opentelemetry 

​

SDK の初期化

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

require

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

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
    service: 'my-service'
});

import

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

HyperDX.init({
    url: 'http://your-otel-collector:4318',
    apiKey: 'YOUR_INGESTION_API_KEY', // Managed ClickStack の場合は省略
    service: 'my-service'
});

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

​

ログ収集の設定

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

Winston

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

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.log

デフォルトでは、console.* メソッドはそのままでサポートされています。追加の設定は不要です。

これは、HDX_NODE_CONSOLE_CAPTURE 環境変数を 0 に設定するか、init 関数に consoleCapture: false を渡すことで無効にできます。

​

エラー収集の設定

ClickStack SDK は、アプリケーション内の未捕捉の例外やエラーを、完全なスタックトレースとコードコンテキスト付きで自動的に収集できます。

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

Express

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

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

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

app.listen(3000);

Koa

const Koa = require("koa");
const Router = require("@koa/router");
const HyperDX = require('@hyperdx/node-opentelemetry');
HyperDX.init({
    url: 'http://your-otel-collector:4318',
    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 によって自動的にインストルメントされ、トレースが収集されます。

• dns
• express
• graphql
• hapi
• http
• ioredis
• knex
• koa
• mongodb
• mongoose
• mysql
• mysql2
• net
• pg
• pino
• redis
• winston

​

代替のインストール方法

​

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

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

NPX を使用

Managed ClickStack

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

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

カスタムエントリポイント（例: Nodemon、ts-node など）

Managed ClickStack

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

HYPERDX_API_KEY='<YOUR_INGESTION_KEY>' OTEL_SERVICE_NAME='<YOUR_APP_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 の例外を自動的に収集する場合、または例外を手動でキャッチする場合は、上記のエラー収集の設定セクションの手順に従ってください。

​

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

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

• amqplib
• AWS Lambda Functions
• aws-sdk
• bunyan
• cassandra-driver
• connect
• cucumber
• dataloader
• dns
• express
• fastify
• generic-pool
• graphql
• grpc
• hapi
• http
• ioredis
• knex
• koa
• lru-memoizer
• memcached
• mongodb
• mongoose
• mysql
• mysql2
• nestjs-core
• net
• pg
• pino
• redis
• restify
• socket.io
• winston