Node.js OpenTelemetry 监控实战:指标采集与导出完整教程

用 OpenTelemetry 为 Node.js 应用建立指标监控:自动 HTTP 指标、Counter/UpDownCounter/Gauge/Histogram 四种仪器用法、指标命名规范,以及通过 OTLP 导出到观测云实现看板与告警。附 Express 完整代码示例。

最佳实践
Node.js OpenTelemetry 监控实战:指标采集与导出完整教程封面

Node.js 的 OpenTelemetry 指标接入以 @opentelemetry/sdk-metrics 为核心,在应用前加载 HTTP 埋点可获得服务端耗时直方图,再用四种仪器补充业务指标。本文使用 OTLP/HTTP 推送;需要提供端点给 Prometheus 抓取时,参见 Node.js 接入 Prometheus。

核心要点速览

  • HTTP 埋点记录耗时直方图,可用 Count 核对已记录的请求次数;
  • 业务指标四种仪器:Counter 计数、UpDownCounter 水位、Gauge 瞬时、Histogram 分布;
  • 指标经 OTLP 周期性导出,本例运行期间每 30 秒收集;
  • 导出后先验证指标名、单位与实例标签,再建立图表和告警。

初始化指标 SDK

示例使用 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 及以上。先保存下面的 collector.yaml,运行 otelcol-contrib --config=collector.yaml,用 debug 导出器查看收到的指标。

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:14318
exporters:
  debug:
    verbosity: detailed
service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [debug]

在空目录安装依赖。把程序保存为 checkout.cjs,运行 node checkout.cjs。HTTP 埋点在 Express 加载前注册,自动指标与业务指标使用同一个 MeterProvider,经 OTLP/HTTP Protobuf 导出到本机 Collector。

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
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;
});

已使用 NodeSDK 的应用,可在现有设置中添加指标 Reader,避免同时注册两份 HTTP 埋点。本例只配置指标导出。

自动 HTTP 指标

程序输出 201 和 503。Collector 中的 http.server.request.duration 以秒计,两种状态码各有一个观测值。用同一组维度的直方图 Count 查看已记录的 HTTP 请求数;示例的业务 Counter 只计一次订单创建。

此处的 HTTP 埋点未自动给直方图加 http.route。路由属性的可用性取决于具体框架和埋点版本。要按业务路由统计,记录实际匹配的模板,示例使用固定的 /orders。旧版埋点可能输出不同名称与单位,复用图表前先核对导出数据。HTTP 埋点包文档 · HTTP 指标语义约定

四种业务指标写法

  • Counter:只记录非负增量,示例中仅成功创建订单时累加,属性为 channel=app。
  • UpDownCounter:进入处理时加一;close 在响应完成或连接提前终止时触发,按相同属性减一。
  • Gauge:用 record 记录瞬时值,示例用固定值 2 表示队列深度。若要在收集时读取实时值,用 ObservableGauge 的 addCallback(result => result.observe(value)),在回调中取当前值。
  • Histogram:示例在 finish 记录从处理开始到响应交给操作系统发送的秒数,两种状态都纳入。提前中断且未到达 finish 的响应不进业务耗时直方图。250 ms 对应 0.25 的桶边界,跨副本聚合前要核对桶布局。

命名纪律:使用稳定名称和明确单位,属性只放聚合维度(如渠道、任务类型),请求 ID、完整 URL 等高基数值不进指标。Node.js 分布式追踪

Node.js 特有的注意点

  • 异步上下文:需要依赖活动上下文时,确认应用已配置相应上下文管理器,并在回调和事件边界验证上下文是否延续;
  • 进程退出:本例关闭 HTTP 服务后等待 provider.shutdown();正式环境应处理终止信号,停止接收新请求,在宽限期内结束在途工作,再等待 SDK 关闭。强制退出或导出失败仍可能丢失末批指标;
  • 多进程实例:PM2 集群的每个进程独立上报。需要按实例比较时,为每个进程设置不同的 service.instance.id。

验证指标导出

使用观测云作为后端时,先启用 DataKit 的 OpenTelemetry 采集器,按实际监听地址配置 exporter;本例的 OTLP/HTTP Protobuf exporter 指向本机 Collector 的 /v1/metrics。DataKit 文档中的默认 HTTP 端口为 9529,指标路径为 /otel/v1/metrics;实际端点、TLS 与认证按部署设置。触发一次已知业务操作,检查 Counter 增量和 Histogram 的单位,再按服务与实例建立查询和告警。

常见问题(FAQ)

Q:自动埋点和我手写的指标会冲突吗? 可能重叠,也可能记录不同总体。给不同测量起清楚的名字,核对导出后的指标标识、单位和维度,避免对同一事件重复计数。

Q:exportIntervalMillis 设多少? 本例使用的定期 Reader 未设置间隔时默认为 60 秒。这里设为 30 秒;实际间隔取决于告警窗口、流量和接收端容量。

Q:可以只导出指标不导出链路吗? 可以。示例只配置指标 Reader;需要链路时再明确配置相应的 tracer provider 和导出器。

Q:TypeScript 项目有额外配置吗? 类型定义不改变模块加载顺序。自动埋点仍应在应用加载目标模块前注册。CommonJS 可用 --require 预加载初始化文件;ESM 应按所用 SDK 的加载指引配置。Node.js OpenTelemetry 设置

系列阅读

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

在线开通,按量计费,真正的云服务!

立即开始

选择观测云版本

代码托管平台