Node.js 接入 Prometheus 监控完全指南
Prometheus 是云原生监控的事实标准。本文实战 Node.js 应用接入：prom-client 自动指标、四大指标类型、PromQL 查询与告警配置，并介绍更省心的托管方案。
Node.js 接 Prometheus 用 prom-client：collectDefaultMetrics() 一行获得运行时指标（内存/GC/事件循环），自定义 Counter/Histogram 记录业务指标，/metrics 端点暴露给 Prometheus 抓取。理解四种指标类型（Counter/Gauge/Histogram/Summary）是用对的前提。
指标与 Prometheus 的心智模型
Prometheus 是拉模型：应用暴露 /metrics 端点，Prometheus 定时抓取存入时序数据库。指标 = 名称 + 标签集合 + 数值。查询用 PromQL，告警用 Alertmanager，可视化用 Grafana——生态分工明确。
自动仪表化：一行启动
npm install prom-client
const client = require('prom-client');
client.collectDefaultMetrics(); // 事件循环延迟、GC、堆内存、CPU 全自动
app.get('/metrics', async (req, res) => {
res.set('Content-Type', client.register.contentType);
res.end(await client.register.metrics());
});
默认指标已经回答了"进程健康吗"——剩下的工作是"业务健康吗"。
四种指标类型
// Counter：只增计数（请求数、错误数）
const requestCounter = new client.Counter({
name: 'http_requests_total', help: 'Total HTTP requests', labelNames: ['method', 'route', 'status'],
});
// Gauge：可增可减（当前连接数、队列长度）
const activeConnections = new client.Gauge({ name: 'websocket_connections', help: 'Current WebSocket connections' });
// Histogram：分布统计（耗时——算 P95/P99）
const duration = new client.Histogram({
name: 'request_duration_seconds', help: 'Request duration in seconds', buckets: [0.1, 0.5, 1, 2, 5],
});
// Summary：类似 Histogram 但分位数在客户端算（聚合受限，优先 Histogram）
选择口诀：累计发生用 Counter，瞬时值用 Gauge，耗时分布用 Histogram。
PromQL 实战查询
# 每秒请求率，使用最近 1 分钟样本
rate(http_requests_total[1m])
# 错误率百分比
100 * sum(rate(http_requests_total{status=~"5.."}[5m])) / sum(rate(http_requests_total[5m]))
# P95 延迟
histogram_quantile(0.95, sum by (le) (rate(request_duration_seconds_bucket[5m])))
告警配置
Prometheus 告警规则示例（由 Alertmanager 路由通知）：错误率 5 分钟超 1% 触发告警、P95 延迟超 2 秒触发告警。告警要配"持续时长"（for: 5m）防毛刺误报。
把 Node.js 指标接入观测云
保留 prom-client 暴露的 /metrics 端点，可以配置 DataKit Prom 采集器的目标地址、认证方式和采集周期，将运行时与业务指标送入观测云。先核对指标类型、单位和低基数标签，再为错误率与延迟设置监控器。指标异常后的调用分析需要额外接入 APM；日志跳转还依赖 trace_id、span_id 以及 service、env、version 的正确注入与一致性。
接入文档：Prometheus 指标采集 · Node.js APM 接入 · 日志与链路关联 · 监控器与告警策略。
常见问题（FAQ）
Q：多实例/集群部署 /metrics 怎么抓？
每个实例被抓取（instance 标签区分），聚合查询时按 route 聚合掉实例维度。K8s 中如已部署 Prometheus Operator，可通过 ServiceMonitor 配置发现；它不是 Kubernetes 默认自带的资源。
Q：短生命周期任务（CronJob）怎么暴露指标？
拉模型抓不到短命进程——用 Pushgateway 模式，或在评估保留与清理策略后用 DataKit 抓取 Pushgateway 暴露的指标或直接写日志/链路埋点。
Q：prom-client 的性能开销？
常规量级（几十个指标、低基数标签）开销可忽略。标签基数失控（把用户 ID 当标签）才是性能灾难的真正来源。
参考文档
本文依据公开文档整理，示例需按项目依赖版本验证；不将文档中的性能描述视为本项目实测结果。
