# @artmizu/nuxt-prometheus 中文文档

规范地址：https://npmcn.com/package/%40artmizu/nuxt-prometheus/

版本：4\.1\.0
npm 元数据更新时间：2026-11-03T08:01:59.205Z
中文译文更新时间：2026-11-06T21:17:44.365Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40artmizu/nuxt-prometheus
原文对照：https://npmcn.com/package/%40artmizu/nuxt-prometheus/?lang=original
源码仓库：https://github.com/artmizu/nuxt-prometheus

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：37.6 kB，33 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.22\.3 \|\| ^24\.15\.0 \|\| \>=26\.0\.0
- 运行依赖：5 个
- 首次发布：2023-01-10T13:49:59.822Z
- 最新版本发布：2026-11-03T08:01:58.917Z
- 近 30 天下载量：42084（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 9 个）

## 中文简介

让你更了解你的应用 如何优化性能和其他生产

## 安装

```sh
npm install @artmizu/nuxt-prometheus
```

也可以使用：`pnpm add @artmizu/nuxt-prometheus`、`yarn add @artmizu/nuxt-prometheus`、`bun add @artmizu/nuxt-prometheus`

## README

![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/artmizu/nuxt-prometheus/release.yml?branch=main)

![Nuxt Prometheus Grafana dashboard](https://raw.githubusercontent.com/artmizu/nuxt-prometheus/main/examples/grafana/dashboard.png)

# Nuxt 的 Prometheus 集成

您的 Nuxt 服务器的 Prometheus 度量衡 。 看看每条路线需要多长时间,外出通话需要多少时间,每条路线返回的是哪个状态代码. Nuxt 2 用户可以使用 [此版本](https://github.com/artmizu/analytics-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 请求 |
| 格拉法纳 | [示例仪表板](https://npmcn.com/package/%40artmizu/nuxt-prometheus/examples/grafana) |

## 路线

您可以用模块选项修改两条路径 .

| 路线 | 目的 |
| --- | --- |
| `/metrics` | 普罗米修斯度量衡 |
| `/health` | 健康检查 |

## 安装

安装软件包管理器 :

```bash
# 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 配置的段落 :

```js
export default {
  modules: ['@artmizu/nuxt-prometheus']
}
```

## 升级为 4.0.0

1.  使用Node.js 22 (22.22.3+),24 (24.15.0+),或26+.
    
2.  更新 `@artmizu/nuxt-prometheus` 改为 `4.0.0`。 。 。 .
    
3.  如果注册自定义衡量标准,则替换 `prom-client` 与 `@prometheus-io/client` 在依赖和导入中:
    
    ```ts
    import { Counter, register } from '@prometheus-io/client'
    ```
    
4.  更新仪表盘查询以使用直方图. 使用 `histogram_quantile()` 为百分位数.
    
5.  添加 `status_code` 所有页面计时度量查询和仪表板。 所有六个页度量标准现在都包括a `status_code` 标签 :
    
    ```promql
    sum by (path) (
      rate(page_total_time_histogram_count{status_code=~"5.."}[5m])
    ) /
    sum by (path) (
      rate(page_total_time_histogram_count[5m])
    )
    ```
    

## 格拉法纳仪表板

一个随时可以使用的仪表板住在 [实例/实例](https://npmcn.com/package/%40artmizu/nuxt-prometheus/examples/grafana),加上一个多克作曲堆栈 启动普罗米修斯和格拉法纳 与已经提供的仪表板.

见 [实例/格拉法纳/README.md](https://npmcn.com/package/%40artmizu/nuxt-prometheus/examples/grafana/README.md) 用于导入步骤,每个面板后面的查询,以及如何将Prometheus指向您的应用.

## 收集的计量

计外 [默认节点.js 度量衡](https://github.com/prometheus/client_js#default-metrics) 国家 `@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`, (中文(简体) ), `https`HTTP/2和GRPC电话 它们不包括原始的TCP连接或数据库客户端.

导出直方图 `_bucket`, (中文(简体) ), `_sum`,以及 `_count` 丛书。 这个 `+Inf` 桶是自动的.

测量变量保持每台最后一次观测值 `(path, status_code)` 成对且永不过期,因此一个很少返回出错的路径可以看起来有 stale 样本;使用直方图进行聚合和仪表板.

SSR出错 无法匹配的路由 404 是由合成的 `/__nuxt_error` 路径及其真实状态代码,所以无法从 `path`。没有 5xx 样本的路径在错误- ratio 查询中缺失,而不是显示 0.

P95跨复制品的总持续时间,以毫秒计:

```promql
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]`

非空列表取代所有三种计时直方图的默认边界. 空列表使用默认值 . 严格增加顺序使用有限度,非负数. 数值以毫秒计.

```ts
export default defineNuxtConfig({
  prometheus: {
    histogramBuckets: [10, 50, 100, 250, 500, 1000],
  },
})
```

### 禁用请求干扰器

-   类型 : `boolean`
-   默认 : `false`
-   说明: 禁用外部请求时间的集合 .

禁用时,仅保留总页数计时标准. 请求和渲染计时仪和直方图因没有其值而省略. 默认节点.js 度量衡, `/metrics`,以及 `/health` 继续提供.

当外出收藏活动时,模块默认可以使Nitro的实验合成上下文被启用. 此上下文保留了针对服务器同时提出的请求,包括SSR请求的输出请求时间. 不包含硝基请求背景的背景请求无助于页面时间安排.

明确 `nitro.experimental.asyncContext: false` 保持不变,但外部要求的时间需要这一特点. 见 [Nitro 合成上下文文档](https://v2.nitro.build/guide/utils#async-context-experimental) 用于运行时间支持和限制.

### 最终点

-   类型 : `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` |

示例用法:

```bash
# 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客户端.

```bash
# 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 已安装](https://grafana.com/docs/k6/latest/set-up/install-k6/),运行 :

```bash
pnpm test:memory
```

PR检查使用局部固定,如果GC后堆积增长超过8 MiB,则失败. 日志、测量和基线堆积快照被保存到 `reports/memory`;失败还包括一个可比较的快照. CI 上传这些文件为 `memory-regression` 艺术品.

此短检查无法检测出每一个缓慢的漏出 。 收集器的生命周期测试单独检查,对于从未解决的请求,没有累积状态.

## 常见问题

### @artmizu/nuxt-prometheus 是什么？

让你更了解你的应用 如何优化性能和其他生产

### 如何安装 @artmizu/nuxt-prometheus？

在项目目录运行 npm install @artmizu/nuxt-prometheus，或使用 pnpm add / yarn add / bun add。

### @artmizu/nuxt-prometheus 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @artmizu/nuxt-prometheus 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @artmizu/nuxt-prometheus 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.22\.3 \|\| ^24\.15\.0 \|\| \>=26\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @artmizu/nuxt-prometheus 可以商用吗？

@artmizu/nuxt-prometheus 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @artmizu/nuxt-prometheus 的下载量有多少？

根据 npm 官方下载统计，@artmizu/nuxt-prometheus 在 2026/10/07 – 2026/11/05 这 30 天内被下载 42,084 次，日均约 1,403 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @artmizu/nuxt-prometheus 还在维护吗？

最新版本 4\.1\.0 发布于 2026/11/03（4 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 9 个；首次发布于 2023/01/10。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。