This is an automated email from the ASF dual-hosted git repository.
Yilialinn pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 55e1cd5c4 docs: fix prometheus plugin documentation (#13275)
55e1cd5c4 is described below
commit 55e1cd5c45a82acbb925b0a6b6b1b9de18586795
Author: Yilia Lin <[email protected]>
AuthorDate: Thu Apr 30 11:24:01 2026 +0800
docs: fix prometheus plugin documentation (#13275)
---
docs/en/latest/plugins/prometheus.md | 16 +++++--
docs/zh/latest/plugins/prometheus.md | 83 ++++++++++++++++++++----------------
2 files changed, 58 insertions(+), 41 deletions(-)
diff --git a/docs/en/latest/plugins/prometheus.md
b/docs/en/latest/plugins/prometheus.md
index d64355fdd..33d87ed80 100644
--- a/docs/en/latest/plugins/prometheus.md
+++ b/docs/en/latest/plugins/prometheus.md
@@ -92,7 +92,7 @@ Reload APISIX for changes to take effect.
| Name | Type | Required | Default | Valid values | Description
|
| ------------- | ------- | -------- | ------- | ------------ |
------------------------------------------ |
-| prefer_name | boolean | | False | | If true, export
Route/Service name instead of their ID in Prometheus metrics. |
+| prefer_name | boolean | False | false | | If true, export
Route/Service name instead of their ID in Prometheus metrics. |
## Metrics
@@ -292,6 +292,14 @@ apisix_etcd_modify_indexes{key="global_rules"} 0
The following example demonstrates how you can disable the Prometheus export
server that, by default, exposes an endpoint on port `9091`, and expose APISIX
Prometheus metrics on a new public API endpoint on port `9080`, which APISIX
uses to listen to other client requests.
+:::caution
+
+If a large quantity of metrics are being collected, the Plugin could take up a
significant amount of CPU resources for metric computations and negatively
impact the processing of regular requests.
+
+To address this issue, APISIX uses [privileged
agent](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/process.md#enable_privileged_agent)
and offloads metric computations to a separate process. This optimization
applies automatically if you use the metric endpoint configured in the
configuration files, as demonstrated [above](#get-apisix-metrics). When you
expose the metric endpoint with the `public-api` Plugin, the offloading and
cached metric serving still apply; howeve [...]
+
+:::
+
Disable the Prometheus export server in the configuration file and reload
APISIX for changes to take effect:
```yaml title="conf/config.yaml"
@@ -300,7 +308,7 @@ plugin_attr:
enable_export_server: false
```
-Next, create a Route with
[`public-api`](../../../en/latest/plugins/public-api.md) Plugin and expose a
public API endpoint for APISIX metrics:
+Next, create a Route with [`public-api`](./public-api.md) Plugin and expose a
public API endpoint for APISIX metrics:
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes/prometheus-metrics"; -X PUT \
@@ -434,7 +442,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
-H "X-API-KEY: ${admin_key}" \
-d '{
"id": "prometheus-route",
-Include the following configurations in the configuration file to add labels
for metrics and reload APISIX for changes to take effect:
+ "uri": "/get",
"name": "extra-label",
"plugins": {
"prometheus": {}
@@ -494,7 +502,7 @@ Create a Stream Route with the `prometheus` Plugin:
curl "http://127.0.0.1:9180/apisix/admin/stream_routes"; -X PUT \
-H "X-API-KEY: ${admin_key}" \
-d '{
-Include the following configurations in `config.yaml` to enable stream proxy
and enable `prometheus` Plugin for stream proxy. Reload APISIX for changes to
take effect:
+ "id": "prometheus-route",
"plugins": {
"prometheus":{}
},
diff --git a/docs/zh/latest/plugins/prometheus.md
b/docs/zh/latest/plugins/prometheus.md
index 21361e358..2cc46005a 100644
--- a/docs/zh/latest/plugins/prometheus.md
+++ b/docs/zh/latest/plugins/prometheus.md
@@ -35,7 +35,7 @@ description: 本文将介绍 prometheus 插件，以及将 APISIX 与 Prometheu
`prometheus` 插件提供将 APISIX 与 Prometheus 集成的能力。
-启用该插件后，APISIX 将开始收集相关指标，例如 API
请求和延迟，并以[基于文本的展示格式](https://prometheus.io/docs/instrumenting/exposition_formats/#exposition-formats)导出到
Prometheus。然后，您可以在 Prometheus 中创建事件监控和警报，以监控 API 网关和 API 的健康状况。
+启用该插件后，APISIX 将开始收集相关指标，例如 API
请求和延迟，并以[基于文本的展示格式](https://prometheus.io/docs/instrumenting/exposition_formats/#exposition-formats)导出到
Prometheus。然后，你可以在 Prometheus 中创建事件监控和警报，以监控 API 网关和 API 的健康状况。
## 静态配置
@@ -84,7 +84,7 @@ plugin_attr:
# - 500
```
-您可以使用 [Nginx 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)创建
`extra_labels`。请参见[为指标添加额外标签](#为指标添加额外标签)。
+你可以使用 [Nginx 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)创建
`extra_labels`。请参见[为指标添加额外标签](#为指标添加额外标签)。
重新加载 APISIX 以使更改生效。
@@ -92,7 +92,7 @@ plugin_attr:
| 名称 | 类型 | 必选项 | 默认值 | 描述
|
| ------------ | --------| ------ | ------ |
----------------------------------------------------- |
-|prefer_name | boolean | 否 | False | 当设置为 `true` 时，则在`prometheus`
指标中导出路由/服务名称而非它们的 `id`。 |
+|prefer_name | boolean | 否 | false | 当设置为 `true` 时，则在`prometheus`
指标中导出路由/服务名称而非它们的 `id`。 |
## 指标
@@ -148,56 +148,56 @@ Prometheus 中有不同类型的指标。要了解它们之间的区别，请参
| 名称 | 描述
|
| ------ |
----------------------------------------------------------------------------------------------------------------------
|
| type | 流量类型，`egress` 或 `ingress`。
|
-| route | 带宽对应的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当 `prefer_name` 为
`true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
-| service | 带宽对应的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当 `prefer_name`
为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
+| route | 请求对应的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当 `prefer_name` 为
`true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
+| service | 请求对应的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当 `prefer_name`
为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
| consumer | 与请求关联的消费者名称。如果请求没有与之关联的消费者，则默认为空字符串。
|
| node | 上游节点的 IP 地址。
|
| request_type | traditional_http / ai_chat / ai_stream
|
| llm_model | 对于非传统的 http 请求，llm 模型的名称
|
-### Labels for `apisix_llm_latency`
+### `apisix_llm_latency` 的标签
-| Name | Description
|
-| ---------- |
-----------------------------------------------------------------------------------------------------------------------------
|
|
-| route_id | 带宽对应的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当
`prefer_name` 为 `true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
-| service_id | 带宽对应的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当
`prefer_name` 为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
+| 名称 | 描述 |
+| ---------- |
-----------------------------------------------------------------------------------------------------------------------------
|
+| route_id | 请求对应的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当
`prefer_name` 为 `true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
+| service_id | 请求对应的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当
`prefer_name` 为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
| consumer | 与请求关联的消费者名称。如果请求没有与之关联的消费者，则默认为空字符串。 |
| node | 上游节点的 IP 地址。
|
| request_type | traditional_http / ai_chat / ai_stream
|
| llm_model | 对于非传统的 http 请求，llm 模型的名称
|
-### Labels for `apisix_llm_active_connections`
+### `apisix_llm_active_connections` 的标签
-| Name | Description
|
+| 名称 | 描述 |
| ---------- |
-----------------------------------------------------------------------------------------------------------------------------
|
-| route | Name of the Route that bandwidth corresponds to. Default to an
empty string if a request does not match any Route.
|
-| route_id | 带宽对应的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当
`prefer_name` 为 `true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
+| route | 请求对应的路由名称。如果请求不匹配任何路由，则默认为空字符串。
|
+| route_id | 请求对应的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当
`prefer_name` 为 `true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
| matched_uri | 匹配请求的路由 URI。如果请求不匹配任何路由，则默认为空字符串。
|
| matched_host | 匹配请求的路由主机。如果请求不匹配任何路由，或路由未配置主机，则默认为空字符串。
|
-| service | Name of the Service that bandwidth corresponds to. Default to
the configured value of host on the Route if the matched Route does not belong
to any Service. |
-| service_id | 带宽对应的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当
`prefer_name` 为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
+| service | 请求对应的服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
+| service_id | 请求对应的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当
`prefer_name` 为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
| consumer | 与请求关联的消费者名称。如果请求没有与之关联的消费者，则默认为空字符串。 |
| node | 上游节点的 IP 地址。
|
| request_type | traditional_http / ai_chat / ai_stream
|
| llm_model | 对于非传统的 http 请求，llm 模型的名称
|
-### Labels for `apisix_llm_completion_tokens`
+### `apisix_llm_completion_tokens` 的标签
-| Name | Description
|
-| ---------- |
-----------------------------------------------------------------------------------------------------------------------------
|
|
-| route_id | 带宽对应的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当
`prefer_name` 为 `true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
-| service_id | 带宽对应的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当
`prefer_name` 为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
+| 名称 | 描述 |
+| ---------- |
-----------------------------------------------------------------------------------------------------------------------------
|
+| route_id | 请求对应的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当
`prefer_name` 为 `true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
+| service_id | 请求对应的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当
`prefer_name` 为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
| consumer | 与请求关联的消费者名称。如果请求没有与之关联的消费者，则默认为空字符串。 |
| node | 上游节点的 IP 地址。
|
| request_type | traditional_http / ai_chat / ai_stream
|
| llm_model | 对于非传统的 http 请求，llm 模型的名称
|
-### Labels for `apisix_llm_prompt_tokens`
+### `apisix_llm_prompt_tokens` 的标签
-| Name | Description
|
-| ---------- |
-----------------------------------------------------------------------------------------------------------------------------
|
|
-| route_id | 带宽对应的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当
`prefer_name` 为 `true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
-| service_id | 带宽对应的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当
`prefer_name` 为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
+| 名称 | 描述 |
+| ---------- |
-----------------------------------------------------------------------------------------------------------------------------
|
+| route_id | 请求对应的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当
`prefer_name` 为 `true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
+| service_id | 请求对应的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当
`prefer_name` 为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
| consumer | 与请求关联的消费者名称。如果请求没有与之关联的消费者，则默认为空字符串。 |
| node | 上游节点的 IP 地址。
|
| request_type | traditional_http / ai_chat / ai_stream
|
@@ -253,9 +253,9 @@ APISIX 延迟
以下示例演示如何从 APISIX 获取指标。
-默认的 Prometheus 指标端点和其他与 Prometheus 相关的配置可以在 [静态配置](#静态配置) 中找到。如果您希望自定义这些配置，更新
`config.yaml` 并重新加载 APISIX。
+默认的 Prometheus 指标端点和其他与 Prometheus 相关的配置可以在 [静态配置](#静态配置) 中找到。如果你希望自定义这些配置，更新
`config.yaml` 并重新加载 APISIX。
-如果您在容器化环境中部署 APISIX，并希望外部访问 Prometheus 指标端点，请按如下方式更新配置文件并重新加载 APISIX：
+如果你在容器化环境中部署 APISIX，并希望外部访问 Prometheus 指标端点，请按如下方式更新配置文件并重新加载 APISIX：
```yaml title="conf/config.yaml"
plugin_attr:
@@ -270,7 +270,7 @@ plugin_attr:
curl "http://127.0.0.1:9091/apisix/prometheus/metrics";
```
-您应该看到类似以下的输出：
+你应该看到类似以下的输出：
```text
# HELP apisix_bandwidth Total bandwidth in bytes consumed per Service in Apisix
@@ -292,6 +292,14 @@ apisix_etcd_modify_indexes{key="global_rules"} 0
以下示例演示如何禁用默认情况下在端口 `9091` 上公开的 Prometheus 导出服务器，并在 APISIX 用于监听其他客户端请求的公共 API
端点上公开 APISIX Prometheus 指标。
+:::caution
+
+如果收集了大量指标，插件可能会占用大量 CPU 资源进行指标计算，从而对常规请求的处理产生负面影响。
+
+为了解决这个问题，APISIX
使用[特权代理](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/process.md#enable_privileged_agent)，将指标收集和计算卸载到一个单独的进程，并通过共享缓存供
HTTP 处理器返回。如果你使用配置文件中配置的指标端点（如[上文](#获取-apisix-指标)所示），此优化将自动生效。如果你使用
`public-api` 插件公开指标端点，仍然会使用这一缓存/卸载机制；不过，请求会额外经过 API 路由处理链，并且指标会暴露在公共监听端口上。
+
+:::
+
在配置文件中禁用 Prometheus 导出服务器，并重新加载 APISIX 以使更改生效：
```yaml title="conf/config.yaml"
@@ -300,7 +308,7 @@ plugin_attr:
enable_export_server: false
```
-接下来，使用 [`public-api`](../../../zh/latest/plugins/public-api.md) 插件创建一个路由，并为
APISIX 指标公开一个公共 API 端点：
+接下来，使用 [`public-api`](./public-api.md) 插件创建一个路由，并为 APISIX 指标公开一个公共 API 端点：
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes/prometheus-metrics"; -X PUT \
@@ -319,7 +327,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/routes/prometheus-metrics"; -X PUT \
curl "http://127.0.0.1:9080/apisix/prometheus/metrics";
```
-您应该看到类似以下的输出：
+你应该看到类似以下的输出：
```text
# HELP apisix_http_requests_total 自 APISIX 启动以来客户端请求的总数。
@@ -392,7 +400,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl "http://127.0.0.1:9091/apisix/prometheus/metrics";
```
-您应该看到类似以下的输出：
+你应该看到类似以下的输出：
```text
# HELP apisix_upstream_status 上游健康检查的状态
@@ -425,7 +433,7 @@ plugin_attr:
- route_name: $route_name # 添加一个额外的 `route_name` 标签，其值为
APISIX 变量 $route_name。
```
-请注意，如果您在标签值中定义了一个变量，但它与任何现有的 [APISIX
变量](https://apisix.apache.org/zh/docs/apisix/apisix-variable/) 和 [Nginx
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html) 不对应，则标签值将默认为空字符串。
+请注意，如果你在标签值中定义了一个变量，但它与任何现有的 [APISIX
变量](https://apisix.apache.org/zh/docs/apisix/apisix-variable/) 和 [Nginx
变量](https://nginx.org/en/docs/http/ngx_http_core_module.html) 不对应，则标签值将默认为空字符串。
使用 `prometheus` 插件创建一个路由：
@@ -452,7 +460,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl -i "http://127.0.0.1:9080/get";
```
-您应该看到 `HTTP/1.1 200 OK` 的响应。
+你应该看到 `HTTP/1.1 200 OK` 的响应。
向 APISIX Prometheus 指标端点发送请求：
@@ -460,7 +468,7 @@ curl -i "http://127.0.0.1:9080/get";
curl "http://127.0.0.1:9091/apisix/prometheus/metrics";
```
-您应该看到类似以下的输出：
+你应该看到类似以下的输出：
```text
# HELP apisix_http_status APISIX 中每个服务的 HTTP 状态代码
@@ -493,6 +501,7 @@ stream_plugins:
curl "http://127.0.0.1:9180/apisix/admin/stream_routes"; -X PUT \
-H "X-API-KEY: ${admin_key}" \
-d '{
+ "id": "prometheus-route",
"plugins": {
"prometheus": {}
},
@@ -511,7 +520,7 @@ curl "http://127.0.0.1:9180/apisix/admin/stream_routes"; -X
PUT \
curl -i "http://127.0.0.1:9100";
```
-您应该看到 `HTTP/1.1 200 OK` 的响应。
+你应该看到 `HTTP/1.1 200 OK` 的响应。
向 APISIX Prometheus 指标端点发送请求：
@@ -519,7 +528,7 @@ curl -i "http://127.0.0.1:9100";
curl "http://127.0.0.1:9091/apisix/prometheus/metrics";
```
-您应该看到类似以下的输出：
+你应该看到类似以下的输出：
```text
# HELP apisix_stream_connection_total APISIX 中每个 Stream Route 处理的总连接数
