Node.js 接入 Prometheus 监控完全指南

Prometheus 是云原生监控的事实标准。本文实战 Node.js 应用接入:Node.js 客户端自动指标、四大指标类型、PromQL 查询与告警配置,并介绍更省心的托管方案。

最佳实践
事件循环与异步任务流转插画

Node.js 接 Prometheus 可用 @prometheus-io/client(原包名 prom-client):collectDefaultMetrics() 一行获得运行时指标(内存/GC/事件循环),自定义 Counter/Histogram 记录业务指标,/metrics 端点暴露给 Prometheus 抓取。理解四种指标类型(Counter/Gauge/Histogram/Summary)是用对的前提。

指标与 Prometheus 的心智模型

Prometheus 是拉模型:应用暴露 /metrics 端点,Prometheus 定时抓取存入时序数据库。指标名与标签集合标识一条时序,每次抓取产生带时间和值的样本。查询用 PromQL,告警条件由 Prometheus 规则评估,Alertmanager 负责分组、静默和通知路由,可视化用 Grafana。

自动仪表化:一行启动

npm install express@5.3.0 @prometheus-io/client@0.16.1

此版本客户端支持 Node.js 22、24 和 26 及以上;本例使用 Node.js 22。将下面的单进程示例保存为 checkout.cjs,运行 node checkout.cjs。监听地址只用于本机测试;部署时应限制 /metrics 的访问范围,并保证采集器可达。

const express = require('express');
const client = require('@prometheus-io/client');

const app = express();
client.collectDefaultMetrics();
const requests = new client.Counter({
  name: 'http_requests_total',
  help: 'Completed checkout HTTP responses',
  labelNames: ['method', 'route', 'status'],
});
const inFlight = new client.Gauge({
  name: 'http_requests_in_flight',
  help: 'Checkout HTTP responses still in progress',
});
const duration = new client.Histogram({
  name: 'request_duration_seconds',
  help: 'Completed checkout response duration in seconds',
  labelNames: ['route'],
  buckets: [0.01, 0.05, 0.1, 0.5, 1, 2, 5],
});

app.get('/metrics', async (req, res) => {
  res.set('Content-Type', client.register.contentType);
  res.end(await client.register.metrics());
});

const checkoutRoute = '/checkout';
for (const status of ['204', '503']) {
  requests.inc({ method: 'POST', route: checkoutRoute, status }, 0);
}

app.post(checkoutRoute, (req, res) => {
  const route = checkoutRoute;
  const stopTimer = duration.startTimer({ route });
  inFlight.inc();

  res.once('finish', () => {
    requests.inc({ method: req.method, route, status: String(res.statusCode) });
    stopTimer();
  });
  res.once('close', () => inFlight.dec());

  res.status(req.query.fail === '1' ? 503 : 204).end();
});

app.listen(3000, '127.0.0.1');
curl -i -X POST 'http://127.0.0.1:3000/checkout'
curl -i -X POST 'http://127.0.0.1:3000/checkout?fail=1'
curl -fsS http://127.0.0.1:3000/metrics

两次请求分别返回 204 和 503,fail=1 只用于演示。默认指标包括事件循环、GC、堆内存和 CPU,部分指标因平台而异。抓到运行时指标,说明采集链路通了;还要看业务请求和错误,才能判断服务是否健康。

四种指标类型

  • Counter:记录已完成的响应,进程重启时计数会重置。示例在 finish 时读取最终状态码。
  • Gauge:记录进行中的响应,可增可减。close 在响应完成或连接提前终止时触发,示例用它扣减。提前断开的响应不计入完成数与延迟分布;需要监控断开时应单独计数。
  • Histogram:将已完成响应的耗时落入累计桶。实例使用相同的桶边界,才能按桶跨实例聚合后估算 P95/P99。把桶设在有意义的阈值附近。
  • Summary:可在应用进程计算分位数,但各实例的分位数不能再聚合为全服务分位数。

选择口诀:累计发生用 Counter,瞬时值用 Gauge,耗时分布用 Histogram。示例用固定路由作为标签,实际应用也应使用路由模板,避免把订单 ID 或查询参数写入标签。

PromQL 实战查询

下面的本机抓取配置将目标归到 checkout-node,并加载同目录的告警文件。

global:
  scrape_interval: 15s
  evaluation_interval: 15s
rule_files:
  - checkout-alerts.yml
scrape_configs:
  - job_name: checkout-node
    static_configs:
      - targets: ["127.0.0.1:3000"]
# 每秒请求率,按路由汇总
sum by (route) (rate(http_requests_total{job="checkout-node"}[5m]))

# 已完成响应中的 5xx 百分比,只显示有流量的窗口
100 * (
  sum(rate(http_requests_total{job="checkout-node",status=~"5.."}[5m]))
  or 0 * sum(rate(http_requests_total{job="checkout-node"}[5m]))
) / (sum(rate(http_requests_total{job="checkout-node"}[5m])) > 0)

# 按路由聚合经典直方图,估算 P95,单位为秒
histogram_quantile(0.95, sum by (le, route) (
  rate(request_duration_seconds_bucket{job="checkout-node"}[5m])
))

先对每条计数时序求 rate(),再聚合,Prometheus 才能在各实例上识别计数器重置。5xx 时序未出现但分母有效时,分子补零;没有流量或样本不足时,不把窗口显示为 0% 错误率。新出现的计数器时序也要有足够抓取样本才能算 rate()。示例先初始化两种状态码的计数,便于采集器在第一次错误前抓到零值。

告警配置

下面的 checkout-alerts.yml 用最近 5 分钟的样本计算错误比例和 P95。规则还要求速率超过每秒 0.2 次、条件连续成立 5 分钟;这些阈值只是示例,应按流量和 SLO 调整。配置 Alertmanager 后,由它路由通知。低流量保护会抑制空窗和极小样本的告警,抓取失败需要另看 up。

groups:
  - name: checkout
    rules:
      - record: checkout:http_requests_per_second:rate5m
        expr: sum(rate(http_requests_total{job="checkout-node"}[5m]))
      - alert: CheckoutHighErrorRatio
        expr: |
          (
            sum(rate(http_requests_total{job="checkout-node",status=~"5.."}[5m]))
            or 0 * checkout:http_requests_per_second:rate5m
          ) / checkout:http_requests_per_second:rate5m > 0.01
          and checkout:http_requests_per_second:rate5m > 0.2
        for: 5m
      - alert: CheckoutHighP95
        expr: |
          histogram_quantile(0.95, sum by (le) (
            rate(request_duration_seconds_bucket{job="checkout-node"}[5m])
          )) > 2
          and checkout:http_requests_per_second:rate5m > 0.2
        for: 5m

把 Node.js 指标接入观测云

保留客户端暴露的 /metrics 端点,可以配置 DataKit Prom 采集器的目标地址、认证方式和采集周期,将运行时与业务指标送入观测云。先核对指标类型、单位和低基数标签,再为错误率与延迟设置监控器。指标异常后的调用分析需要额外接入 APM;日志跳转还依赖 trace_id、span_id 以及 service、env、version 的正确注入与一致性。

接入文档:Prometheus 指标采集 · Node.js APM 接入 · 日志与链路关联 · 监控器与告警策略。

常见问题(FAQ)

Q:多实例/集群部署 /metrics 怎么抓?

分别抓取每个实例(用 instance 标签区分),避免同一个负载均衡地址在不同进程之间切换。Node.js cluster 的每个 worker 有独立 registry;可分别暴露端点,或按客户端文档由主进程通过 AggregatorRegistry 汇总。K8s 中如已部署 Prometheus Operator,并正确匹配选择器,可通过 ServiceMonitor 发现目标;它不是 Kubernetes 默认自带的资源。

Q:短生命周期任务(CronJob)怎么暴露指标?

任务可能在两次抓取之间结束。与特定机器无关的服务级批任务,可将结果或最后成功时间推给 Pushgateway,再由 Prometheus 或 DataKit 抓取。Pushgateway 会保留推送的时序直到显式删除,需要清理失效的分组;逐机器任务或仅需逐次执行记录时,按场景用文本文件采集或日志/链路。

Q:prom-client 的性能开销?

开销随采集指标、标签基数、直方图桶数和抓取频率变化,应结合应用负载实测。用户 ID 等高基数标签会增加应用端时序和抓取体积,也会增加后端存储与查询开销。


参考文档

本文依据公开文档整理,示例需按项目依赖版本验证;不将文档中的性能描述视为本项目实测结果。

延伸阅读

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

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

立即开始

选择观测云版本

代码托管平台