Nuxt 的 Prometheus 集成
您的 Nuxt 服务器的 Prometheus 度量衡 。 看看每条路线需要多长时间,外出通话需要多少时间,每条路线返回的是哪个状态代码. Nuxt 2 用户可以使用 此版本。 。 。 .
你为什么想要
- 带a的路线时间
status_code标签。 可以将慢答与错误区分开来. - 用于请求、渲染和总时间的直方图。 他们一起工作
histogram_quantile()在格拉法纳. - 外出通话时间不设网络截取. HTTP/2和GRPC继续工作,仍然被计算在内.
- 格拉法纳仪表板和多克堆栈.
- 您的负载平衡器的健康检查路径 .
支持的堆栈
| 区域 | 支助 |
|---|---|
| 坚果 | 3.x和4.x (中文(简体) ) |
| 节点.js | 22.22.3+, 24.1.5.0+, 26+ |
| 阿宝 | 1.3.11 (测试) |
| 德诺 | 2.8.3(测试) |
| 硝基预设 | node-server, (中文(简体) ), bun, (中文(简体) ), deno-server |
| 外出通话数 | fetch 和乌迪西, http 财务报告和审定财务报表 https,HTTP/2,gRPC (中文(简体) ) |
| 未计外拨 | 原始 TCP 连接、 数据库客户端和 XMLHttp 请求 |
| 格拉法纳 | 示例仪表板 |
路线
您可以用模块选项修改两条路径 .
| 路线 | 目的 |
|---|---|
/metrics | 普罗米修斯度量衡 |
/health | 健康检查 |
安装
安装软件包管理器 :
# using nuxi, it automatically appends the module in your nuxt.config
npx nuxi@latest module add prometheus
# using npm
npm install @artmizu/nuxt-prometheus
# using yarn
yarn add @artmizu/nuxt-prometheus
# using pnpm
pnpm add @artmizu/nuxt-prometheus
将模块添加到 modules 您的 Nuxt 配置的段落 :
export default {
modules: ['@artmizu/nuxt-prometheus']
}
升级为 4.0.0
-
使用Node.js 22 (22.22.3+),24 (24.15.0+),或26+.
-
更新
@artmizu/nuxt-prometheus改为4.0.0。 。 。 . -
如果注册自定义衡量标准,则替换
prom-client与@prometheus-io/client在依赖和导入中:import { Counter, register } from '@prometheus-io/client' -
更新仪表盘查询以使用直方图. 使用
histogram_quantile()为百分位数. -
添加
status_code所有页面计时度量查询和仪表板。 所有六个页度量标准现在都包括astatus_code标签 :sum by (path) ( rate(page_total_time_histogram_count{status_code=~"5.."}[5m]) ) / sum by (path) ( rate(page_total_time_histogram_count[5m]) )
格拉法纳仪表板
一个随时可以使用的仪表板住在 实例/实例,加上一个多克作曲堆栈 启动普罗米修斯和格拉法纳 与已经提供的仪表板.
见 实例/格拉法纳/README.md 用于导入步骤,每个面板后面的查询,以及如何将Prometheus指向您的应用.
收集的计量
计外 默认节点.js 度量衡 国家 @prometheus-io/client,本模块收集以下自定义度量标准:
| 度量衡 | 类型 | 标签 | 说明 |
|---|---|---|---|
page_render_time | 高盖 | path, (中文(简体) ), status_code | 制作页面花费的时间(总数减去外部请求时间),以毫秒计 |
page_request_time | 高盖 | path, (中文(简体) ), status_code | 页面处理期间用于外部 API 请求的时间, 以毫秒计 |
page_total_time | 高盖 | path, (中文(简体) ), status_code | 完成请求的总时间(以毫秒计) |
page_render_time_histogram | 直方图 | path, (中文(简体) ), status_code, (中文(简体) ), le 装入桶 | 页面渲染时间分布, 以毫秒计 |
page_request_time_histogram | 直方图 | path, (中文(简体) ), status_code, (中文(简体) ), le 装入桶 | 外部 API 请求时间的分布, 以毫秒计 |
page_total_time_histogram | 直方图 | path, (中文(简体) ), status_code, (中文(简体) ), le 装入桶 | 请求时间总数分布情况(以毫秒计) |
所有自定义的公尺名称都可以与 prefix 选项,例如 myapp_page_render_time。 。 。 .
这个 page_request_time 计量标准包括外出 fetch, (中文(简体) ), http, (中文(简体) ), httpsHTTP/2和GRPC电话 它们不包括原始的TCP连接或数据库客户端.
导出直方图 _bucket, (中文(简体) ), _sum,以及 _count 丛书。 这个 +Inf 桶是自动的.
测量变量保持每台最后一次观测值 (path, status_code) 成对且永不过期,因此一个很少返回出错的路径可以看起来有 stale 样本;使用直方图进行聚合和仪表板.
SSR出错 无法匹配的路由 404 是由合成的 /__nuxt_error 路径及其真实状态代码,所以无法从 path。没有 5xx 样本的路径在错误- ratio 查询中缺失,而不是显示 0.
P95跨复制品的总持续时间,以毫秒计:
histogram_quantile(0.95, sum by (le, path) (rate(page_total_time_histogram_bucket[5m])))
选项
您可以通过模块选项和 nuxt 配置属性传递 prometheus。 。 。 .
启用
- 类型 :
boolean - 默认 :
true - 说明:运行时启用或禁用普罗米修斯集成. 设定为
false,不采集测量值,也不注册钩. 这使得您可以用模块构建应用程序, 但在特定环境中禁用它 .
动词
- 类型 :
boolean - 默认 :
true - 描述: dev模式下的额外日志,关于外部 API 请求的页面渲染时间和时间
健康检查
- 类型 :
boolean - 默认 :
true - 说明:打开和关闭健康检查路线
健康检查
- 类型 :
string - 默认 :
/health - 描述: 健康检查url路径
舞会
- 类型 :
string - 默认 :
/metrics - 描述: Prometheus 出口国 URL 路径
前缀
- 类型 :
string - 默认: 无前缀
- 描述: 计量名称的可选前缀
直方图框
- 类型 :
number[] - 默认 :
[5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000]
非空列表取代所有三种计时直方图的默认边界. 空列表使用默认值 . 严格增加顺序使用有限度,非负数. 数值以毫秒计.
export default defineNuxtConfig({
prometheus: {
histogramBuckets: [10, 50, 100, 250, 500, 1000],
},
})
禁用请求干扰器
- 类型 :
boolean - 默认 :
false - 说明: 禁用外部请求时间的集合 .
禁用时,仅保留总页数计时标准.
请求和渲染计时仪和直方图因没有其值而省略.
默认节点.js 度量衡, /metrics,以及 /health 继续提供.
当外出收藏活动时,模块默认可以使Nitro的实验合成上下文被启用. 此上下文保留了针对服务器同时提出的请求,包括SSR请求的输出请求时间. 不包含硝基请求背景的背景请求无助于页面时间安排.
明确 nitro.experimental.asyncContext: false 保持不变,但外部要求的时间需要这一特点.
见 Nitro 合成上下文文档 用于运行时间支持和限制.
最终点
- 类型 :
boolean - 默认 :
true - 说明:是否曝光
/metrics终点 设定为false,度量衡仍在内部收集,但端点没有登记。 这使得您可以通过程序通过register对象从@prometheus-io/client并把它们暴露在一个单独的内部港口.
运行时环境变量
所有选项都可以在运行时按照 Nuxt 常规通过环境变量配置 NUXT_PUBLIC_PROMETHEUS_<OPTION_NAME>数字 :
| 环境变量 | 选项 | 示例 |
|---|---|---|
NUXT_PUBLIC_PROMETHEUS_ENABLED | enabled | false |
NUXT_PUBLIC_PROMETHEUS_VERBOSE | verbose | false |
NUXT_PUBLIC_PROMETHEUS_HEALTH_CHECK | healthCheck | false |
NUXT_PUBLIC_PROMETHEUS_METRICS_ENDPOINT | metricsEndpoint | false |
NUXT_PUBLIC_PROMETHEUS_PREFIX | prefix | myapp_ |
NUXT_PUBLIC_PROMETHEUS_HISTOGRAM_BUCKETS | histogramBuckets | [10, 100, 1000] |
NUXT_PUBLIC_PROMETHEUS_DISABLE_REQUEST_INTERCEPTOR | disableRequestInterceptor | true |
示例用法:
# Disable metrics endpoint in production while keeping collection active
NUXT_PUBLIC_PROMETHEUS_METRICS_ENDPOINT=false node .output/server/index.mjs
# Use custom prefix
NUXT_PUBLIC_PROMETHEUS_PREFIX=myapp_ node .output/server/index.mjs
发展
该构建使用TypeScript 5.9.3,因为目前的Nuxt模块构建器不支持TypeScript 7编译器API.
外出请求时间由 src/runtime/collector在节点上,收藏家订阅 undici:request:*, (中文(简体) ), http.client.* 财务报告和审定财务报表 http2.client.stream.* 诊断渠道。 Bun和Deno的包装 fetch, (中文(简体) ), http, (中文(简体) ), https 财务报告和审定财务报表 http2.connect因为那里没有或没有完整的频道 适配器都无法截取连接,因此HTTP/2和GRPC的交通也和以前一样有效. 两者都被计算在内,因为gRPC使用Node.js HTTP/2客户端.
# Install dependencies
pnpm install
# Prepare the module (build types and module)
pnpm run dev:prepare
# Start development server with playground
pnpm run dev
# Run tests
pnpm test
重要内容: 修改模块源代码后,必须运行 pnpm run dev:prepare 在测试前重建模块.
内存回归检查
与 k6 已安装,运行 :
pnpm test:memory
PR检查使用局部固定,如果GC后堆积增长超过8 MiB,则失败.
日志、测量和基线堆积快照被保存到 reports/memory;失败还包括一个可比较的快照.
CI 上传这些文件为 memory-regression 艺术品.
此短检查无法检测出每一个缓慢的漏出 。 收集器的生命周期测试单独检查,对于从未解决的请求,没有累积状态.