Copilot commented on code in PR #13864:
URL: https://github.com/apache/apisix/pull/13864#discussion_r3829016909
##########
docs/zh/latest/plugins/limit-count.md:
##########
@@ -62,8 +62,8 @@ import TabItem from '@theme/TabItem';
| rejected_msg | string | 否 | | 非空 | 请求因超出阈值而被拒绝时返回的响应主体。 |
| policy | string | 否 | local |
["local","redis","redis-cluster","redis-sentinel"] | 速率限制计数器的策略。如果是
`local`，则计数器存储在本地内存中。如果是 `redis`，则计数器存储在 Redis 实例上。如果是 `redis-cluster`，则计数器存储在
Redis 集群中。如果是 `redis-sentinel`，则计数器存储在通过 Sentinel 发现的 Redis 主节点上。 |
| allow_degradation | boolean | 否 | false | | 如果为 true，则允许 APISIX
在插件或其依赖项不可用时继续处理没有插件的请求。 |
-| show_limit_quota_header | boolean | 否 | true | | 如果为 true，则在响应标头中包含
`X-RateLimit-Limit` 以显示总配额和 `X-RateLimit-Remaining` 以显示剩余配额。 |
-| sync_interval | number | 否 | | -1 或 >= 0.1 | Redis 类策略的延迟同步间隔，单位为秒。设置为 `-1`
可显式禁用延迟同步。 |
+| show_limit_quota_header | boolean | 否 | true | | 如果为 true，则在响应标头中包含
`X-RateLimit-Limit`、`X-RateLimit-Remaining` 和 `X-RateLimit-Reset`。 |
Review Comment:
在 `rules` 模式下并不会生成这里列出的原始标头名：每条规则都会使用显式配置或数字形式的前缀，因此实际标头类似
`X-Jack-RateLimit-Reset` 或 `X-1-RateLimit-Reset`。请说明这些名称仅适用于单限制模式，并将规则模式指向
`rules.header_prefix`。
This issue also appears on line 66 of the same file.
##########
docs/zh/latest/plugins/prometheus.md:
##########
@@ -148,15 +161,49 @@ Prometheus 中有不同类型的指标。要了解它们之间的区别，请参
| 名称 | 描述
|
| ------ |
----------------------------------------------------------------------------------------------------------------------
|
-| code | 上游节点返回的 HTTP 响应代码。
|
+| code | 返回给客户端的 HTTP 响应代码。
|
| route | HTTP 状态来源的路由 ID，当 `prefer_name` 为 `false`（默认）时，使用路由 ID，当
`prefer_name` 为 `true` 时，使用路由名称。如果请求不匹配任何路由，则默认为空字符串。 |
| matched_uri | 匹配请求的路由 URI。如果请求不匹配任何路由，则默认为空字符串。
|
| matched_host | 匹配请求的路由主机。如果请求不匹配任何路由，或路由未配置主机，则默认为空字符串。
|
| service | HTTP 状态来源的服务 ID，当 `prefer_name` 为 `false`（默认）时，使用服务 ID，当
`prefer_name` 为 `true` 时，使用服务名称。如果匹配的路由不属于任何服务，则默认为路由上配置的主机值。 |
| consumer | 与请求关联的消费者名称。如果请求没有与之关联的消费者，则默认为空字符串。
|
| node | 上游节点的 IP 地址。
|
-| request_type | traditional_http / ai_chat / ai_stream
|
-| llm_model | 对于非传统的 http 请求，llm 模型的名称
|
+| request_type | 请求类别：`traditional_http`、`ai_chat` 或 `ai_stream`。
|
+| request_llm_model | 客户端请求的模型名称。
|
+| llm_model | AI 请求实际使用的目标模型。优先使用 AI 实例中配置的模型，否则使用客户端请求的模型；传统 HTTP
流量中为空字符串。 |
+| response_source | 响应来源：`apisix` 表示由 APISIX 生成，`nginx` 表示 NGINX
代理错误，`upstream` 表示来自上游服务的响应。 |
+
+### `apisix_stream_active_connections` 的标签
+
+接受会话时，该 gauge 会递增；会话结束时递减，因此无需等到会话结束即可反映实时并发量。
+
+| 名称 | 描述 |
+| --- | --- |
+| listen_addr | 客户端连接的监听地址，例如 `0.0.0.0:9100`。 |
+
+### `apisix_stream_status` 的标签
+
+上游连接建立后发生的故障在 NGINX Stream `$status` 中都可能显示为
200，因此仅凭该值无法区分超时、连接重置和正常关闭。此指标利用运行时记录的终止原因，将会话归类到 NGINX Stream
使用的状态代码中，不引入自定义状态代码。
+
+| 名称 | 描述 |
+| --- | --- |
+| code | 会话结束方式：`200` 表示正常关闭；`400` 表示客户端重置或预读数据无效等客户端问题；`403` 表示被访问规则拒绝；`500`
表示内部错误；`502` 表示连接失败、重置或空闲超时等上游或传输问题；`503` 表示被连接数限制拒绝。 |
Review Comment:
导出器并未把 `200` 严格限定为正常关闭。`STREAM_REASON_TO_CODE` 还会把 `shutdown` 映射为
`200`，而缺失或无法识别的 `stream_session_reason` 也会回退为 `200`。说明段落和标签行都应保留这种歧义。
##########
docs/en/latest/plugins/prometheus.md:
##########
@@ -106,25 +109,35 @@ Collapsing a label's value to `""` keeps the label
registered in the metric sche
See [Reduce Metric Cardinality by Disabling
Labels](#reduce-metric-cardinality-by-disabling-labels) for an example.
-The `request_llm_model` and `llm_model` label values are derived from
client-supplied model names. To bound cardinality, APISIX truncates each of
these label values to 128 bytes before recording. If you do not need per-model
breakdowns, list `request_llm_model` and `llm_model` under `disabled_labels`
for the LLM metrics to collapse them to a single empty-valued series.
+The `request_llm_model` label comes from the model requested by the client.
The `llm_model` label identifies the effective target model: it uses the model
configured on the AI instance when present, otherwise it uses the requested
model. To bound cardinality, APISIX truncates each label value to 128 bytes
before recording. If you do not need per-model breakdowns, list
`request_llm_model` and `llm_model` under `disabled_labels` for the LLM metrics
to collapse them to a single empty-valued series.
## Metrics
There are different types of metrics in Prometheus. To understand their
differences, see [metrics
types](https://prometheus.io/docs/concepts/metric_types/).
-The following metrics are exported by the `prometheus` Plugin by default. See
[get APISIX metrics](#get-apisix-metrics) for an example. Note that some
metrics, such as `apisix_batch_process_entries`, are not readily visible if
there are no data.
+The `prometheus` Plugin registers the following metrics. See [get APISIX
metrics](#get-apisix-metrics) for an example. A metric series appears only
after its data source is active. For example, Stream metrics require
`prometheus` to be enabled as a Stream Plugin, LLM metrics require AI traffic,
AI cache metrics require the `ai-cache` Plugin, and
`apisix_batch_process_entries` requires a batch-processing Plugin to have data.
Review Comment:
This wording makes the table exhaustive, but configured xRPC protocols
register additional Prometheus metrics through `apisix/stream/xrpc.lua`; for
example, Redis xRPC adds `apisix_redis_commands_total` and
`apisix_redis_commands_latency_seconds`
(`apisix/stream/xrpc/protocols/redis/metrics.lua`). Either list those metrics
or explicitly scope this as a non-exhaustive/core list.
This issue also appears on line 134 of the same file.
##########
docs/zh/latest/plugins/prometheus.md:
##########
@@ -106,25 +109,35 @@ plugin_attr:
示例请参见[通过禁用标签降低指标基数](#通过禁用标签降低指标基数)。
-`request_llm_model` 与 `llm_model` 标签值来源于客户端提供的模型名称。为了限制基数，APISIX
在记录前会将这两个标签值截断为 128 字节。如果你不需要按模型细分，可将 `request_llm_model` 和 `llm_model` 列入 LLM
指标的 `disabled_labels`，从而将其折叠为一条空值时间序列。
+`request_llm_model` 标签来自客户端请求的模型。`llm_model` 标签表示实际使用的目标模型：优先使用 AI
实例中配置的模型，否则使用客户端请求的模型。为了限制基数，APISIX 在记录前会将这两个标签值分别截断为 128 字节。如果你不需要按模型细分，可将
`request_llm_model` 和 `llm_model` 列入 LLM 指标的 `disabled_labels`，从而将其折叠为一条空值时间序列。
## 指标
Prometheus
中有不同类型的指标。要了解它们之间的区别，请参见[指标类型](https://prometheus.io/docs/concepts/metric_types/)。
-以下是 `prometheus` 插件默认导出的指标。有关示例，请参见[获取 APISIX 指标](#获取 APISIX 指标)。请注意，一些指标，例如
`apisix_batch_process_entries`，如果没有数据，将不可见。
+`prometheus` 插件会注册以下指标。有关示例，请参见[获取 APISIX 指标](#获取 APISIX
指标)。只有对应数据源启用后，相关指标序列才会出现。例如，Stream 指标要求将 `prometheus` 启用为 Stream 插件，LLM 指标要求存在
AI 流量，AI 缓存指标要求启用 `ai-cache` 插件，而 `apisix_batch_process_entries`
只有在批处理插件产生数据后才会出现。
Review Comment:
当前措辞把表格描述为完整列表，但配置的 xRPC 协议还会通过 `apisix/stream/xrpc.lua` 注册额外指标。例如，Redis
xRPC 会添加 `apisix_redis_commands_total` 和
`apisix_redis_commands_latency_seconds`（见
`apisix/stream/xrpc/protocols/redis/metrics.lua`）。请补充这些指标，或明确说明这里只列出核心指标。
This issue also appears on line 134 of the same file.
##########
docs/en/latest/plugins/limit-count.md:
##########
@@ -61,8 +61,8 @@ You may see the following rate limiting headers in the
response:
| rejected_msg | string | False
| | non-empty | The response body
returned when a request is rejected for exceeding the threshold. |
| policy | string | False
| local | ["local","redis","redis-cluster","redis-sentinel"]
| The policy for the rate limiting counter. If it is `local`, the counter is
stored in local memory. If it is `redis`, the counter is stored on a Redis
instance. If it is `redis-cluster`, the counter is stored in a Redis cluster.
If it is `redis-sentinel`, the counter is stored on the Redis master discovered
through Sentinel. |
| allow_degradation | boolean | False
| false | | If true, allow APISIX
to continue handling requests without the plugin when the plugin or its
dependencies become unavailable. |
-| show_limit_quota_header | boolean | False
| true | | If true, include
`X-RateLimit-Limit` to show the total quota and `X-RateLimit-Remaining` to show
the remaining quota in the response header. |
-| sync_interval | number | False
| | -1 or >= 0.1 | The delayed
synchronization interval in seconds for Redis-based policies. Set to `-1` to
disable delayed synchronization explicitly. |
+| show_limit_quota_header | boolean | False
| true | | If true, include
`X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset` in the
response headers. |
Review Comment:
In `rules` mode these exact header names are never emitted: `get_rules`
assigns each rule a configured or numeric prefix, so the response contains
names such as `X-Jack-RateLimit-Reset` or `X-1-RateLimit-Reset`. Qualify the
standard names as applying to single-limit mode and point rules users to
`rules.header_prefix`.
This issue also appears on line 65 of the same file.
--
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]
