Node.js の OpenTelemetry メトリクス入門:HTTP 計装と OTLP
OpenTelemetry JavaScript SDK で Express の HTTP と業務メトリクスを計測し、リクエスト数と OTLP/HTTP Protobuf 送信をローカルで確認します。
注文 API が 503 を返し始めても、成立した注文数はほとんど変わらないことがあります。HTTP の処理時間を記録するヒストグラムには失敗した応答も入り、業務カウンターはアプリケーションが注文を受け付けたときだけ増えます。両方を計測しておくと、トラフィックの変化と注文結果の変化を分けて見られます。
このガイドでは Express、OpenTelemetry JavaScript Metrics SDK、ローカルの Collector を使います。SDK は OTLP/HTTP でメトリクスをまとめて送ります。Prometheus に /metrics をスクレイプさせる場合は、Node.js を Prometheus で監視する手順を参照してください。
ローカルに OTLP の受信先を用意する
設定を collector.yaml として保存し、otelcol-contrib --config=collector.yaml を実行します。HTTP レシーバーはループバックで待ち受け、debug エクスポーターが受信したメトリクスをログに出します。
receivers:
otlp:
protocols:
http:
endpoint: 127.0.0.1:14318
exporters:
debug:
verbosity: detailed
service:
pipelines:
metrics:
receivers: [otlp]
exporters: [debug]
Node.js 22.16.0、Express 5.3.0、OpenTelemetry Metrics SDK 3.1.1、HTTP 計装とエクスポーター 0.301.1、Collector Contrib 0.165.0 で検証しました。この組み合わせの OpenTelemetry パッケージは Node.js 22.15.0 以降が必要です。空のディレクトリで依存パッケージを入れます。
npm init -y
npm install --save-exact express@5.3.0 \
@opentelemetry/api@1.10.0 @opentelemetry/resources@3.1.1 \
@opentelemetry/sdk-metrics@3.1.1 \
@opentelemetry/instrumentation@0.301.1 \
@opentelemetry/instrumentation-http@0.301.1 \
@opentelemetry/exporter-metrics-otlp-proto@0.301.1
Express の読み込み前に HTTP 計装を登録する
自動計装と手動計装には同じ MeterProvider を使います。定期収集用の Reader は OTLP/HTTP エクスポーターにデータを渡し、エクスポーターが Protobuf で送信します。設定した Collector のアドレスはローカルの検証用です。
コードを checkout.cjs に保存し、node checkout.cjs を実行します。プログラムは合成リクエストを二つ送り、応答を最後まで読み取って 201 と 503 を表示します。テストサーバーを閉じてから shutdown() を呼び、最後のメトリクスを収集して送信します。
const { once } = require('node:events');
const { MeterProvider, PeriodicExportingMetricReader } = require('@opentelemetry/sdk-metrics');
const { resourceFromAttributes } = require('@opentelemetry/resources');
const { OTLPMetricExporter } = require('@opentelemetry/exporter-metrics-otlp-proto');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const { HttpInstrumentation } = require('@opentelemetry/instrumentation-http');
const exporter = new OTLPMetricExporter({
url: 'http://127.0.0.1:14318/v1/metrics',
});
const provider = new MeterProvider({
resource: resourceFromAttributes({ 'service.name': 'checkout-node' }),
readers: [new PeriodicExportingMetricReader({ exporter, exportIntervalMillis: 30_000 })],
});
const unregister = registerInstrumentations({
meterProvider: provider,
instrumentations: [new HttpInstrumentation()],
});
const express = require('express');
const app = express();
const meter = provider.getMeter('example.com/checkout');
const created = meter.createCounter('orders.created', { unit: '{order}' });
const inFlight = meter.createUpDownCounter('orders.inflight', { unit: '{request}' });
const depth = meter.createGauge('orders.queue.depth', { unit: '{order}' });
const duration = meter.createHistogram('orders.process.duration', {
unit: 's',
advice: { explicitBucketBoundaries: [0.01, 0.05, 0.1, 0.25, 0.5, 1, 5] },
});
app.post('/orders', (req, res) => {
const started = performance.now();
const attributes = { route: '/orders' };
inFlight.add(1, attributes);
res.once('close', () => inFlight.add(-1, attributes));
res.once('finish', () => {
duration.record((performance.now() - started) / 1000, attributes);
});
depth.record(2);
if (req.query.fail === '1') {
res.sendStatus(503);
return;
}
created.add(1, { channel: 'app' });
res.sendStatus(201);
});
async function run() {
const server = app.listen(0, '127.0.0.1');
try {
await once(server, 'listening');
const { port } = server.address();
for (const suffix of ['', '?fail=1']) {
const response = await fetch(`http://127.0.0.1:${port}/orders${suffix}`, {
method: 'POST',
signal: AbortSignal.timeout(5_000),
});
await response.arrayBuffer();
console.log(response.status);
}
} finally {
try {
if (server.listening) {
await new Promise((resolve, reject) => {
server.close(error => error ? reject(error) : resolve());
});
}
} finally {
try {
await provider.shutdown();
} finally {
unregister();
}
}
}
}
run().catch(error => {
console.error(error);
process.exitCode = 1;
});
実環境でも、計装対象のモジュールを読み込む前に登録します。CommonJS では起動用ファイルを --require で先に読み込めます。ESM では実行環境とデプロイ方式に応じて SDK のローダー手順を確認してください。TypeScript の型情報だけで、計装の読み込み順が変わることはありません。 Node.js の OpenTelemetry セットアップ(英語)
自動計装の HTTP ヒストグラムを確認する
Collector の出力で service.name=checkout-node と http.server.request.duration を探します。この HTTP 計装ではヒストグラムの単位が s で、ステータスコード別の Count はそれぞれ一です。ほかの属性もそろえたとき、Count は記録された HTTP リクエスト数を表します。業務用の orders.created では、channel=app の注文が一件記録されます。
自動で付与されるルート属性は、計装パッケージやフレームワークによって変わります。この例の自動 HTTP ヒストグラムには http.route が付きません。業務用ヒストグラムでは固定の /orders を属性にしています。/orders/:id のようなルートではマッチしたテンプレートを使い、URL 全体やリクエスト ID をメトリクス属性に含めないようにします。古い HTTP 計装では名前や単位が異なる場合があるので、既存のダッシュボードを使う前に実際の出力を確認します。 HTTP 計装パッケージ · HTTP メトリクスの規約
測りたい値に合わせて計測器を選ぶ
| 知りたいこと | 計測器 | 例での記録方法 |
|---|---|---|
| 注文が何件成立したか | Counter | 成立したときに 0 以上の増分を加えます。 |
| 処理中のリクエストは何件か | UpDownCounter | 開始時に加え、応答完了や接続の終了時に同じ属性で引きます。 |
| 現在のキューの深さは | Gauge | 観測値を記録します。例では固定値の二です。収集時に読む場合は ObservableGauge の addCallback(result => result.observe(value)) を使い、コールバック内で値を取得します。 |
| ハンドラーの処理に何秒かかったか | Histogram | 応答の finish で経過秒数を記録します。成功・失敗の両方を含みます。 |
finish は応答を送信用に OS へ渡した時点です。ここではハンドラー開始からサーバー側の時間を測ります。接続が途中で切れても close で処理中の件数を戻せます。業務用の処理時間に入るのは finish に達した応答です。 Node.js の応答イベント(英語)
例では 250 ms にバケット境界があります。複数のレプリカをまとめるときはバケット構成をそろえ、アラートのしきい値の近くに境界を置きます。レプリカには共通のサービス名を使い、プロセスごとに比較するなら service.instance.id を個別に設定します。PM2 クラスターでも同じ考え方です。
同じメトリクスを Guance に送る
DataKit の OpenTelemetry インプットを有効にし、エクスポーターの送信先に実際の OTLP レシーバーを指定します。ドキュメント上の HTTP の既定値はポート 9529、メトリクスのパスは /otel/v1/metrics です。記事のローカル Collector は専用ポートの /v1/metrics を使っています。本番では環境に合わせて TLS と認証を設定します。 DataKit の OpenTelemetry インプット
決めた数のリクエストを送り、Guance が受け取ったメトリクス名、単位、属性、ヒストグラムの形式を確認してから、チャートやモニターを設定します。注文数と一緒に HTTP ステータス別の件数を見ておけば、注文の総数に隠れる失敗の増加にも気づけます。 Guance のモニター設定
運用時によくある質問
トレースを送らずにメトリクスを集められますか? 可能です。この例ではメトリクスの Reader だけを設定しています。NodeSDK をすでに使っているアプリケーションでは、既存設定に Reader を追加し、同じ HTTP 計装を二重に登録しないようにします。
自動計装と独自のメトリクスは重複しますか? 測定の対象が同じなら重複することがあります。対象が分かる名前を付け、受信側でメトリクスの識別情報、単位、属性を確認します。業務カウンターと HTTP のヒストグラムが異なる対象を数える場合は、結果も異なります。
エクスポート間隔はどれくらいですか? Reader の明示設定がなければ既定は 60 秒です。例では実行中を 30 秒とし、終了時にも収集します。アラートの評価ウィンドウ、トラフィック、レシーバーの処理余力に合わせます。
プロセス終了時にメトリクスは送られますか? 本番では終了シグナルを処理して新規リクエストの受け付けを止め、猶予時間内に処理を終えたあとで SDK の終了を待ちます。強制終了、タイムアウト、受信エラーでは最後のバッチを失う場合があります。
