Copilot commented on code in PR #13275:
URL: https://github.com/apache/apisix/pull/13275#discussion_r3122024790
##########
docs/zh/latest/plugins/prometheus.md:
##########
@@ -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)，将指标计算卸载到一个单独的进程。如果您使用配置文件中配置的指标端点（如[上文](#获取-apisix-指标)所示），此优化将自动生效。如果您使用
`public-api` 插件公开指标端点，则不会受益于此优化。
Review Comment:
此处新增的注意事项写到：如果使用 `public-api` 插件公开指标端点，将“不会受益于”特权代理优化。但当前实现中，指标收集由仅在
`privileged agent` 进程中运行的定时器完成，并通过 `prometheus-cache` 共享字典缓存后由 HTTP 处理器返回（包括
`public-api` 通过 API router 暴露的端点）。建议调整表述为：使用 `public-api`
仍会使用该缓存/卸载机制，但会带来额外的请求路径开销/暴露在公共监听端口上；或明确说明在什么条件下才会绕过该优化。
```suggestion
为了解决这个问题，APISIX
使用[特权代理](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/process.md#enable_privileged_agent)，将指标收集和计算卸载到一个单独的进程，并通过共享缓存供
HTTP 处理器返回。如果您使用配置文件中配置的指标端点（如[上文](#获取-apisix-指标)所示），此优化将自动生效。如果您使用
`public-api` 插件公开指标端点，仍然会使用这一缓存/卸载机制；不过，请求会额外经过 API 路由处理链，并且指标会暴露在公共监听端口上。
```
##########
docs/zh/latest/plugins/prometheus.md:
##########
@@ -155,49 +155,49 @@ Prometheus 中有不同类型的指标。要了解它们之间的区别，请参
| 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` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
Review Comment:
In the translated LLM-metrics label tables (e.g., `apisix_llm_latency`), the
label descriptions still say “带宽对应…” (bandwidth) even though these metrics are
not bandwidth-related. Please update the wording to refer to the LLM
request/metric context (e.g., “请求对应的路由/服务 …”) so the descriptions match the
metric names.
##########
docs/en/latest/plugins/prometheus.md:
##########
@@ -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 the 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). If you
expose the metric endpoint with the `public-api` Plugin, you will not benefit
from this optimization.
Review Comment:
The new caution note says that exposing the metrics endpoint via the
`public-api` Plugin “will not benefit” from the privileged-agent optimization.
In current implementation, metrics collection is performed by a timer that only
runs in the `privileged agent` process and the HTTP handler (including the
API-router endpoint used by `public-api`) serves cached metrics from
`prometheus-cache` (see `apisix/plugins/prometheus/exporter.lua`:
`init_exporter_timer()` + `get_cached_metrics()`). Please adjust the wording to
reflect that the offloading/caching still applies when using `public-api` (the
main difference is request-path overhead / exposure on the public listener), or
clarify the exact condition under which the optimization would be bypassed.
```suggestion
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; however, the endpoint is then exposed on the
public listener and requests to it go through the normal public API request
path, which can add request-path overhead compared with the dedicated export
server.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
