メインコンテンツまでスキップ
メインコンテンツまでスキップ

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に送信するためにロガーにトランスポートを追加する必要があります。その他の種類のロガーを使用している場合は、お問い合わせいただくか、適用可能であればプラットフォーム統合の1つ（例えば、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

ユーザー情報またはメタデータの添付​

特定の属性や識別子（例：ユーザーIDまたはメール）に関連するすべてのイベントを簡単にタグ付けするには、setTraceAttributes関数を呼び出します。この関数を呼び出すと、宣言された属性で現在のトレースに関連するすべてのログ/spanがタグ付けされます。この関数は、リクエスト/トレース内でできるだけ早く呼び出すことをお勧めします（例：Expressミドルウェアスタックの早い段階で）。

これにより、すべてのログ/spanが適切な識別子で自動的にタグ付けされ、後で検索する際に便利になります。手動で識別子をタグ付けして伝播させる必要はありません。

userId、userEmail、userName、およびteamNameは、セッションUIに対応する値を埋め込みますが、省略することもできます。その他の追加値も指定でき、イベントの検索に使用できます。

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

app.use((req, res, next) => {
  // Get user information from the request...

  // Attach user information to the current trace
  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のドキュメントを参照してください。

自動計測されたライブラリ​

次のライブラリは、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から自動的に例外をキャプチャするか、手動で例外を捕まえるための指示に従ってください。エラー収集の設定セクションを上記参照してください。

自動計測されたライブラリ​

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