Node.js 性能监控实战:Performance API + 指标体系

从代码段计时到完整指标体系:本文实战 Node.js Performance API 测量数据库查询、API 请求、数据处理耗时,并对接指标系统实现生产级性能监控。

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

Node.js 性能监控的落地方案:用 perf_hooks 的 performance.measure() 测量关键代码段耗时,配合 prom-client 暴露请求数/耗时/内存等指标到 /metrics,由指标系统采集聚合。四个必测点:数据库查询、外部 API 调用、数据处理、模板渲染。

Performance API 基础

const { performance, PerformanceObserver } = require('node:perf_hooks');

const observer = new PerformanceObserver((list) => {
  for (const entry of list.getEntriesByName('db-query')) {
    console.log('db-query', entry.duration);
  }
});
observer.observe({ entryTypes: ['measure'] });

let sequence = 0;
async function timeQuery(query) {
  const start = 'db-query:start:' + (++sequence);
  performance.mark(start);
  try {
    return await query();
  } finally {
    performance.measure('db-query', { start, end: performance.now() });
    performance.clearMarks(start);
    performance.clearMeasures('db-query');
  }
}

先注册观察器,再调用 await timeQuery(() => db.query(sql))(在异步函数内)。entry.duration 的单位是毫秒;发给以秒计的直方图时要除以 1,000。示例只打印结果,生产环境可换成指标记录,并在停止观测时调用 observer.disconnect()。

四个必测代码段

1. 数据库查询:包裹 ORM/驱动调用,按表/操作打标签——慢查询是头号性能杀手。

2. 外部 API 请求:第三方调用的延迟直接传导到你的响应时间——按目标服务打标签,超时与失败也要计。

3. 数据处理:批量转换、聚合计算——数据量增长让今天的"秒级"变明年的"分钟级",趋势要早看见。

4. 渲染与序列化:SSR/大 JSON 序列化是隐藏的 CPU 消耗点。

自定义指标暴露

const express = require('express');
const client = require('prom-client');
const app = express();
const registry = new client.Registry();

client.collectDefaultMetrics({ register: registry });
const httpDuration = new client.Histogram({
  name: 'http_request_duration_seconds',
  help: 'Duration of completed HTTP responses in seconds',
  labelNames: ['method', 'route', 'status'],
  buckets: [0.01, 0.05, 0.1, 0.3, 0.5, 1, 2, 5],
  registers: [registry],
});

const orderRoute = '/api/orders/:id';
app.get(orderRoute, (req, res) => {
  const end = httpDuration.startTimer();
  res.once('finish', () => end({
    method: req.method,
    route: orderRoute,
    status: String(res.statusCode),
  }));
  res.json({ ok: true });
});

app.get('/metrics', async (_req, res, next) => {
  try {
    const body = await registry.metrics();
    res.set('Content-Type', registry.contentType).end(body);
  } catch (error) {
    next(error);
  }
});

app.listen(3000, '127.0.0.1');

示例使用 Express 和旧包名下的 prom-client@15.1.3,只计入已发送完成的订单路由响应;客户端提前断开要单独计量。该库的后续版本以 @prometheus-io/client 发布,升级前查看上游变更日志。请求标签使用路由模板,不能用包含具体 ID 的路径。默认运行时指标与自定义指标注册到同一个 Registry,采集端才能在 /metrics 读到两类指标。示例仅在本机监听,实际部署时将采集地址限制在监控网络或加上访问控制。

Histogram 是关键选择:平均耗时掩盖长尾,P95/P99 可以帮助看长尾。经典 Histogram 的分位数由桶内插值得出,是估计值;样本过少时先看请求量。

指标查询与应用

采集后的典型查询:各路由 P95 耗时排序找瓶颈(用 histogram_quantile 时保留 le,并在聚合前对桶计数器取 rate)、错误率(status=~"5.." 的请求速率除以同范围总请求速率)监控、请求量趋势容量规划。指标的性价比在于"长期趋势"——单次耗时波动是噪声,趋势变化才是信号。

把运行时指标与接口延迟放到一起

Node.js 接口变慢可能来自事件循环阻塞、GC 压力或外部依赖。使用 prom-client 等方式输出运行时指标并配置 DataKit Prom 采集,再为请求路径接入观测云 APM。事件循环延迟、事件循环利用率(ELU)与 CPU 使用率含义不同。monitorEventLoopDelay 的分位数以纳秒返回,换算毫秒要除以 1,000,000。先对齐服务、环境和实例标签,观察延迟上升时哪些信号同步变化;运行时指标与 tracing 是独立配置,不应把安装一个探针当作全部接入完成。

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

常见问题(FAQ)

Q:Histogram 的 buckets 怎么设?

按业务响应时间分布设:以示例的 10ms 到 5s 为起点,若阈值是 300ms,就保留 0.3 秒这个桶边界。桶越多,时序数量越多;同一聚合范围的实例要采用一致的桶边界。

Q:指标标签(label)可以加用户 ID 吗?

绝对不行——高基数标签(用户 ID、请求 ID)会让时序数量爆炸。标签只放低基数字段(方法、路由、状态码),明细数据走日志/链路。

Q:开发环境需要这套吗?

本地开发用 console.time 足够。指标体系的价值在生产环境与压测环境——那是性能真相所在。


参考文档

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

延伸阅读

获取专属方案

联系我们

加入社区

微信扫码
加入官方交流群

立即体验

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

立即开始

选择观测云版本

代码托管平台