Node.js OpenTelemetry 指標實作:HTTP 埋點與 OTLP
用 OpenTelemetry JavaScript SDK 量測 Express HTTP 和業務指標,並在本機確認請求計數及 OTLP/HTTP Protobuf 匯出。
結帳端點開始回傳 503,訂單成立數卻可能幾乎沒變。HTTP 耗時直方圖會收進失敗回應,業務計數器只在應用程式接受訂單時增加。兩個數字分開看,才能分辨請求流量和業務結果的變化。
本文以 Express、OpenTelemetry JavaScript Metrics SDK 和本機 Collector 示範。SDK 透過 OTLP/HTTP 主動傳送批次資料。若要提供 /metrics 給 Prometheus 定期抓取,可參考另一篇用 Prometheus 監控 Node.js。
啟動本機 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。定期讀取器透過 OTLP/HTTP 匯出器傳送資料,編碼採用 Protobuf。程式中的 Collector 位址用於本機回送測試。
將程式存成 checkout.cjs,執行 node checkout.cjs。程式會送出兩筆合成請求,讀完回應內容並印出 201 和 503。關閉測試伺服器之後,shutdown() 會要求 provider 收集並匯出最後一批指標。
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 了解已記錄的 HTTP 請求數。orders.created 是業務計數器,channel=app 的值為一。
自動路由屬性取決於埋點和框架。本例的自動 HTTP 直方圖沒有 http.route,業務耗時直方圖使用固定路由 /orders。遇到 /orders/:id 之類的路由時,應使用實際匹配的樣板,將完整 URL 和請求 ID 留在指標屬性之外。舊版 HTTP 埋點可能輸出不同名稱和單位,沿用儀表板前先核對版本的實際輸出。 HTTP 埋點套件 · HTTP 指標慣例
依量測目標選擇指標類型
| 想知道什麼 | 指標類型 | 範例做法 |
|---|---|---|
| 成立了幾筆訂單? | Counter | 成功時加上非負的增量。 |
| 有幾個請求還在處理? | UpDownCounter | 開始時加一,連線終止或回應結束時以相同屬性減一。 |
| 佇列目前有多深? | Gauge | 記錄觀測值,範例固定為二。若要在收集時讀取佇列,可用 ObservableGauge 的 addCallback(result => result.observe(value)),在回呼中取得目前值。 |
| 處理函式花了多久? | Histogram | 在回應的 finish 事件記錄經過的秒數,兩種狀態碼均納入。 |
finish 表示已將回應交由作業系統傳送。範例從處理函式開始計時,量到的是伺服器端時間。連線提前終止時,仍可透過 close 將處理中計數扣回。業務耗時直方圖只記錄到達 finish 的回應。 Node.js 回應事件(英文)
範例包含 250 ms 桶邊界。要跨副本彙總,應使用相容的桶配置,並在告警門檻附近設邊界。多個副本可共用同一個服務名稱。若需逐程序比較,應為每個程序設不同的 service.instance.id,PM2 叢集也一樣。
將同一批指標送到觀測雲
使用 DataKit 時,先啟用 OpenTelemetry 收集器,再將匯出器指向實際的 OTLP 接收端。DataKit 文件的預設 HTTP 埠是 9529,指標路徑為 /otel/v1/metrics。本文的回送 Collector 則在自己的埠使用 /v1/metrics。請依部署方式設定 TLS 和驗證。 DataKit OpenTelemetry 收集器(簡體中文)
先送出已知數量的請求,核對觀測雲收到的名稱、單位、屬性和直方圖格式,再設圖表與監控器。一起看 HTTP 狀態碼和訂單量,才不會漏掉訂單總量持平時的失敗增加。 觀測雲監控設定(簡體中文)
部署時的常見問題
可以收集指標而不匯出追蹤嗎? 可以。範例只配置指標讀取器。已使用 NodeSDK 的應用程式,可在現有設定加入讀取器,避免重複註冊同一套 HTTP 埋點。
自動指標和自訂指標會重疊嗎? 有可能。用不同名稱區分實際量測的對象,並在接收端確認指標身分、單位與維度。業務 Counter 和自動 HTTP 直方圖的統計母體不同時,數字也會不同。
讀取器多久匯出一次? 此讀取器未明確指定間隔時,預設是 60 秒。範例執行期間設為 30 秒,關閉時另外收集。請依告警視窗、流量及接收端容量選擇。
程序結束時,指標還會送出去嗎? 正式環境應處理終止訊號,停止接收新請求,在寬限期內等處理中的工作結束,再等待 SDK 關閉。強制結束、匯出逾時或接收失敗仍可能遺失最後一批資料。
