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

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', { // Send logs info and above
          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();

// Add your routes, etc.

// Add this after all routes,
// but before any and other error-handling middlewares are defined
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

Attach user information or metadata​

To easily tag all events related to a given attribute or identifier (ex. user id or email), you can call the setTraceAttributes function which will tag every log/span associated with the current trace after the call with the declared attributes. It's recommended to call this function as early as possible within a given request/trace (ex. as early in an Express middleware stack as possible).

This is a convenient way to ensure all logs/spans are automatically tagged with the right identifiers to be searched on later, instead of needing to manually tag and propagate identifiers yourself.

userId, userEmail, userName, and teamName will populate the sessions UI with the corresponding values, but can be omitted. Any other additional values can be specified and used to search for events.

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

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

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

  next();
});

Make sure to enable beta mode by setting HDX_NODE_BETA_MODE environment variable to 1 or by passing betaMode: true to the init function to enable trace attributes.

export HDX_NODE_BETA_MODE=1

Google Cloud Run​

If you're running your application on Google Cloud Run, Cloud Trace automatically injects sampling headers into incoming requests, currently restricting traces to be sampled at 0.1 requests per second for each instance.

The @hyperdx/node-opentelemetry package overwrites the sample rate to 1.0 by default.

To change this behavior, or to configure other OpenTelemetry installations, you can manually configure the environment variables OTEL_TRACES_SAMPLER=parentbased_always_on and OTEL_TRACES_SAMPLER_ARG=1 to achieve the same result.

To learn more, and to force tracing of specific requests, please refer to the Google Cloud Run documentation.

Auto-instrumented libraries​

The following libraries will be automatically instrumented (traced) by the SDK:

Alternative installation​

Run the Application with ClickStack OpenTelemetry CLI​

Alternatively, you can auto-instrument your application without any code changes by using the opentelemetry-instrument CLI or using the Node.js --require flag. The CLI installation exposes a wider range of auto-instrumented libraries and frameworks.

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

The OTEL_SERVICE_NAME environment variable is used to identify your service in the HyperDX app, it can be any name you want.

Enabling exception capturing​

To enable uncaught exception capturing, you'll need to set the HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE environment variable to 1.

HDX_NODE_EXPERIMENTAL_EXCEPTION_CAPTURE=1

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

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

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