OpenTelemetryによるNode.jsのオブザーバビリティ:トレース、メトリクス、ログの実践ガイド

Programming tutorial - IT technology blog
Programming tutorial - IT technology blog

背景: OpenTelemetryで本番環境の障害を乗り切る

ローカル環境でのNode.jsのデバッグはシンプルです。しかし、高負荷な本番環境となると話は別です。タイムセール中に決済エンドポイントのp99レイテンシが45msから4.2秒へと跳ね上がったとき、標準のconsole.log出力は判読不能なテキストの壁と化します。非同期コールバックによってタイムスタンプは前後し、インデックスのないテーブルへのPostgresクエリが停滞しているのか、StripeのWebhookがタイムアウトしたのか、それとも12MBのJSONペイロードがシングルスレッドのイベントループをブロックしているのか、推測に頼らざるを得なくなります。

OpenTelemetry(OTel)は、そのような当て推量を不要にします。Cloud Native Computing Foundation(CNCF)が支援するこのプロジェクトは、テレメトリのベンダー中立な標準規格を提供します。特定のプロプライエタリなAPMエージェントにコードベースを縛り付けることなく、OTelは3つの基本的なテレメトリシグナルの出力方法を標準化します。

  • トレース(Traces): 注入されたトレースIDとスパンIDを使用して、関数、マイクロサービス、データベースを横断するHTTPリクエストの経路を追跡します。
  • メトリクス(Metrics): 一定のローリング期間で算出される数値の集計(リクエストスループット、GC停止時間、イベントループのラグなど)。
  • ログ(Logs): アクティブなトレースIDに直接紐付けられた構造化イベント。数秒でエラーのコンテキストを特定可能にします。

これら3つのシグナルを関連付けることで、深夜の障害対応をわずか30秒の根本原因調査へと変貌させることができます。

インストール: OpenTelemetry Node.js SDKの追加

OTelはモジュール型アーキテクチャを採用しているため、アプリケーションに必要なコンポーネントのみをインストールします。ここでは、自動計装とOpenTelemetry Protocol(OTLP)エクスポーターを備えたExpressサービスをセットアップする方法を説明します。

mkdir node-otel-demo
cd node-otel-demo
npm init -y

# ExpressとOpenTelemetry APIをインストール
npm install express @opentelemetry/api

# SDKランタイム、自動計装パッケージ、OTLPエクスポーターをインストール
npm install @opentelemetry/sdk-node \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/sdk-metrics \
  @opentelemetry/resources \
  @opentelemetry/semantic-conventions \
  @opentelemetry/exporter-trace-otlp-proto \
  @opentelemetry/exporter-metrics-otlp-proto

各コンポーネントの役割は以下のとおりです。

  • @opentelemetry/api: アプリケーションコードにトレース機能やコンテキスト操作機能を提供するAPIパッケージ。
  • @opentelemetry/sdk-node: アプリケーションの起動前にトレーサープロバイダー、メトリクスリーダー、バックグラウンドエクスポーターを初期化するランタイムエンジン。
  • @opentelemetry/auto-instrumentations-node: http、express、pg、ioredis、mongodbなどのモジュールを自動的にラップする、コミュニティ主導で保守されているフック集。
  • @opentelemetry/exporter-*-otlp-proto: Grafana Tempo、Jaeger、SigNozなどのコレクターにHTTP/gRPC経由でテレメトリを送信する高性能なprotobufエクスポーター。

設定: Node.jsを適切に計装する

初期化の順序は極めて重要です。OpenTelemetryは、アプリケーションが依存パッケージを読み込む前にNode.jsのコアモジュールにパッチを適用する必要があります。もしExpressやpgがOTelよりも先にインポートされてしまうと、外部ネットワークソケットやルートハンドラーは計装されずに実行されてしまいます。

ステップ1: 計装モジュールの作成

プロジェクトのルートディレクトリにinstrumentation.jsファイルを作成します。このロジックはWebサーバーの起動処理とは分離しておきます。

// instrumentation.js
const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
const { PeriodicExportingMetricReader, ConsoleMetricExporter } = require('@opentelemetry/sdk-metrics');
const { Resource } = require('@opentelemetry/resources');
const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');

const traceExporter = new OTLPTraceExporter({
  url: process.env.OTEL_EXPORTER_OTLP_TRACES_ENDPOINT || 'http://localhost:4318/v1/traces',
});

const metricReader = new PeriodicExportingMetricReader({
  exporter: new ConsoleMetricExporter(),
  exportIntervalMillis: 15000,
});

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'order-api-service',
    [SemanticResourceAttributes.SERVICE_VERSION]: '1.2.0',
    [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: process.env.NODE_ENV || 'production',
  }),
  traceExporter,
  metricReader,
  instrumentations: [getNodeAutoInstrumentations()],
});

sdk.start();

// プロセス終了時に残りのスパンをフラッシュ
const shutdown = () => {
  sdk.shutdown()
    .then(() => console.log('[OTel] SDKのシャットダウンが完了しました'))
    .catch((err) => console.error('[OTel] SDKのシャットダウン中にエラーが発生しました', err))
    .finally(() => process.exit(0));
};

process.on('SIGTERM', shutdown);
process.on('SIGINT', shutdown);

ステップ2: トレースと関連付けられたログを持つサンプルアプリの構築

app.jsを作成します。重要なビジネスロジックの周りにカスタムスパンを作成し、JSONログのペイロードにトレースメタデータを注入します。

// app.js
const express = require('express');
const opentelemetry = require('@opentelemetry/api');

const app = express();
const PORT = process.env.PORT || 3000;

// 標準出力ログをアクティブなスパンに関連付ける
function logWithTrace(level, message, data = {}) {
  const activeSpan = opentelemetry.trace.getActiveSpan();
  const spanContext = activeSpan ? activeSpan.spanContext() : null;

  const payload = {
    timestamp: new Date().toISOString(),
    level,
    message,
    trace_id: spanContext ? spanContext.traceId : 'none',
    span_id: spanContext ? spanContext.spanId : 'none',
    ...data,
  };
  console.log(JSON.stringify(payload));
}

app.get('/api/orders/:id', async (req, res) => {
  const orderId = req.params.id;
  const tracer = opentelemetry.trace.getTracer('order-tracer');

  // 細かな実行時間を計測するために明示的な子スパンを作成
  return tracer.startActiveSpan('process-order-logic', async (span) => {
    try {
      span.setAttribute('app.order.id', orderId);
      logWithTrace('info', '注文リクエストを処理中', { orderId });

      // 120msのデータベースクエリをシミュレート
      await new Promise((resolve) => setTimeout(resolve, 120));

      if (orderId === 'invalid') {
        throw new Error('注文の検索に失敗しました: プライマリレプリカにレコード 0x404 が存在しません');
      }

      span.setStatus({ code: opentelemetry.SpanStatusCode.OK });
      res.status(200).json({ status: 'success', orderId, totalCents: 4999 });
    } catch (err) {
      span.recordException(err);
      span.setStatus({
        code: opentelemetry.SpanStatusCode.ERROR,
        message: err.message,
      });
      logWithTrace('error', err.message, { orderId });
      res.status(404).json({ error: err.message });
    } finally {
      span.end();
    }
  });
});

app.listen(PORT, () => {
  console.log(`サーバーがポート ${PORT} で待機中です`);
});

検証と本番環境へのデプロイ

メインプロセスを開始する前に、Node固有の--requireフラグを使用して計装ファイルをプリロードします。これにより、Expressが初期化される前にテレメトリのフックが確実にアタッチされます。

node --require ./instrumentation.js app.js

1. テストリクエストの送信

2つのサンプルリクエストを送信して、OTelが正常なコードパスと異常なコードパスをどのように処理するかを確認します。

# 1. 成功リクエスト(OKスパンと標準の200 HTTPトレースを生成)
curl -i http://localhost:3000/api/orders/order_8829

# 2. 失敗リクエスト(例外を記録し、スパンステータスをERRORに設定)
curl -i http://localhost:3000/api/orders/invalid

2. トレースとログの関連付けの実践

アプリケーションの標準出力を確認します。ログフォーマッターは、一致するW3Cのtrace_idとspan_idを含む構造化JSONレコードを出力します。

{"timestamp":"2026-11-16T11:50:00.123Z","level":"error","message":"注文の検索に失敗しました: プライマリレプリカにレコード 0x404 が存在しません","trace_id":"4bf92f3577b34da6a3ce929d0e0e4736","span_id":"00f067aa0ba902b7","orderId":"invalid"}

午前2時にPagerDutyからアラートが届いた場合でも、ログアグリゲーター(Loki、Datadog、Elasticsearchなど)でエラーメッセージを検索し、trace_idを取得してJaegerやGrafana Tempoに貼り付けるだけです。すると、エラーが発生する前にデータベースの待機で正確に120ms費やされていたという完全なウォーターフォールが即座に可視化されます。

3. 本番環境に向けた次のステップ

  • OTel Collectorによる分離: 本番環境のNode.jsインスタンスからサードパーティのエンドポイントにテレメトリを直接送信することは避けてください。KubernetesのサイドカーまたはローカルデーモンセットとしてOpenTelemetry Collectorをデプロイします。これにより、スパンのバッチ処理(例:512レコードのバッファ)、ペイロードの圧縮が行われ、Nodeのイベントループに対するネットワークオーバーヘッドが軽減されます。
  • ヘッドベースサンプリングの設定: 毎秒10,000リクエストの規模では、すべてのトレースを100%記録するとストレージとコストが無駄になります。OTEL_TRACES_SAMPLER=parentbased_traceidratioを設定し、OTEL_TRACES_SAMPLER_ARG=0.05の比率を指定することで、例外を100%キャプチャしながら正常なトラフィックは5%のみを記録するようにします。
  • 標準の環境変数を使用する: コレクターのエンドポイントをコード内にハードコードしないでください。デプロイマニフェスト経由でOTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318やOTEL_SERVICE_NAME=order-apiを設定します。
Share: