版本：1.8.0

指标参考

AISIX 以 Prometheus 文本格式公开运行指标。Prometheus 服务器或其他兼容采集器可抓取这些指标，用于仪表盘、告警和 PromQL 查询。

默认在专用监听器上启用 Prometheus 指标。默认启动配置如下：

config.yaml
observability:
  metrics:
    prometheus:
      enabled: true
      addr: 0.0.0.0:9090
      path: /metrics

Prometheus 从此监听器抓取 GET /metrics。

指标端点按设计不需要认证。请确保该监听器仅对监控网络开放。

每次抓取端点时，AISIX 都会公开配置状态。其他指标系列会在 AISIX 首次记录相应活动时注册，因此流量指标可能不会在启动后立即出现。请通过代理发送请求，然后再次抓取，即可看到相应序列。

下方目录列出默认标签。有关按指标增减标签的配置及所有支持的变量，参见指标标签与变量。

指标目录

搜索指标名称、描述、标签和值，或按指标系列和类型筛选目录。展开条目即可查看详细信息。

指标: 85
系列: 12

查询行为

指标类型

counter

持续累加并在进程重启前只增不减的值，例如请求总数或 Token 总数。使用 rate() 计算其变化速率。

gauge

可增可减的当前值，例如活跃请求数或剩余配额。

histogram

按可配置分桶统计的观测值。计算百分位数前，可以聚合 _bucket、_sum 和 _count 序列。

summary

由各网关实例计算分位数的观测值。摘要也公开 _sum 和 _count，但其分位数无法跨实例聚合。

搜索指标

共 85 个条目，当前显示 85 个

请求指标

跟踪请求结果以及代理当前正在处理的工作。

指标条目：8

详细请求标签

所有面向客户端的路由都会记录本族：模型端点、/v1/models、OAuth protected-resource 发现文档、MCP、A2A 及其 Agent Card、文件、批处理和微调路由、realtime 会话，以及透传路由。网关在认证阶段以 401 或 403 拒绝的请求同样计入，model="unresolved"，覆盖以这种方式认证调用方的所有路由：模型端点、/v1/models、文件、批处理和微调路由、MCP 和 A2A。/livez 和 /readyz 探针不计入。/v1/models、发现文档、Agent Card 和认证拒绝，1.7.1 及更早版本不计入。

本族的每个计数器都是每次客户端请求采样一次，其 status 是请求最终结束时的状态。对流式响应而言，这是流结束时的状态——调用方中途离开为 499，上游中断或超时为 502 或 504——并且样本在流结束时采集，因此在一批长流进行期间，rate() 会滞后大约一个流的时长。1.5.0 及更早版本在响应开始时以调用方收到的 200 对流式请求采样，透传路由除外。第一个目标失败、随后由回退目标成功处理的请求，在这里只是一个 status="200" 样本；它所恢复的那次失败在本族中完全没有体现。统计上游尝试请使用部署指标，查看单次尝试请使用用量日志。

对于三个详细请求计数器，stream 记录客户端是否请求流式响应。is_fallback 记录请求是否由回退目标处理，并且不会出现在延迟指标中。

provider_key_name 和 user_name 是对应 ID 的可读名称。每个名称与其 ID 一一对应，因此不会增加新的序列维度。在控制面提供名称前，user_name 为 unknown。

详细请求计数器还支持 api_key_name 和 team_name，即认证所用 API Key 及其团队的显示名称。二者都不是默认标签：需将其加入 observability.metrics.labels 中该指标族的标签列表。没有显示名称的 API Key、或网关尚未收到其名称的团队，报告为 unknown；重命名会产生新的序列。1.5.0 及更早版本不输出该标签。

失败请求与成功请求携带相同的 provider、upstream_model 和 Provider Key 标签，因此仅凭本族指标即可计算按 Provider 或按 Provider Key 的失败率。这些上游标签记录请求最后选定的目标：在重试或回退场景下，即调用方最终收到其错误的那次尝试。只有当请求从未选定任何目标时它们才为 unknown，例如模型不存在、被输入护栏拦截、被预算拒绝，或请求体在派发前即被拒绝。

inbound_protocol 是由标准化端点推导出的有界协议类型集合。Anthropic 协议端点报告 anthropic；/mcp、/a2a 及 A2A Agent Card、/v1/realtime 和 /passthrough_route 分别报告 mcp、a2a、realtime 和 passthrough；其余网关端点报告 openai。在途请求仪表使用相同的值。

upstream_protocol 是该协议对的另一半：AISIX 与实际处理该请求的上游通信时所使用的协议。它按照与请求转发相同的规则从所选目标的 Provider Key 解析得出，因此报告的是请求实际被转换成的传输格式——openai、anthropic、bedrock、vertex 或 azure-openai；当请求完全没有选中上游时报告 unknown。同时按两个标签分组即可区分原生流量与跨协议转换流量，参见区分跨协议转换流量。

请勿用 provider 代替 upstream_protocol。provider 是开放的厂商字符串，同一厂商可以通过不同的适配器接入，因此从厂商名到协议的 PromQL 映射需要手工维护，并且会对所有自定义厂商和 OpenAI 兼容厂商给出错误结果。

endpoint 始终是标准化的路由模板，而不是原始请求路径。带路径参数的路由会合并为一条序列，例如 /v1/batches/:id、/v1/videos/:id 和 /mcp/{server}；/passthrough/ 下的路径使用 /passthrough_route，无法识别的路径报告为 other。两个发现文档分别为 /.well-known/oauth-protected-resource 和 /.well-known/oauth-protected-resource/mcp；A2A Agent Card 为 /a2a/{agent}/.well-known/agent-card.json，与 /a2a 的 Agent 调用分开。

aisix_requests_total 。描述：兼容性序列中的代理请求结果，覆盖的端点范围最广。。类型：counter 。标签数量：4 个标签

`outcome` 的值

success, client_error, rate_limited, upstream_error

success 表示 HTTP 200–399；client_error 表示除 429 外的 HTTP 400–499；rate_limited 表示所有 HTTP 429（网关限流、预算拒绝或上游自己返回的 429）；其他所有状态均映射为 upstream_error。

行为

A2A Agent 调用使用 provider="a2a" 和 model="a2a"。

PromQL 示例

sum(rate(aisix_requests_total[5m])) by (outcome)

aisix_llm_requests_total 。描述：模型推理请求的结果，包括成功和失败的请求。。类型：counter 。标签数量：16 个标签

`inbound_protocol` 的值

openai, anthropic, realtime, passthrough

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

`stream` 的值

false, true

`is_fallback` 的值

false, true

`outcome` 的值

success, client_error, rate_limited, upstream_error

行为

覆盖调用模型的端点：聊天补全、补全、消息、Token 计数、响应、向量嵌入、重排序、/v1/systemone 和 /v1/decisions、音频、图像生成和编辑、视频和 realtime 会话。未调用模型的请求只计入 aisix_proxy_requests_total，包括 MCP 工具调用、A2A Agent 调用和 Agent Card、不透明的透传中继、文件、批处理和微调管理路由、/v1/models，以及 OAuth 发现文档。

当 AISIX 把透传路由请求的协议识别为某个模型端点所服务的协议（聊天、Anthropic Messages、响应、补全、向量嵌入、图像生成或编辑、重排序）时，该请求会以 endpoint="/passthrough_route" 计入此处。其 model 是请求正文中的 model 归一到已配置模型名称后的值，未命中任何模型时为 unresolved，正文没有 model 时为 unknown；其 upstream_model 为 unknown。同一 model 也用于它在代理请求指标族中的样本。其他透传请求（包括 DashScope 原生正文）只计入代理指标族，model="passthrough"。1.6.0 及更早版本不发射，它们把所有透传请求只计入代理指标族。

在分发前被拒绝的请求（例如请求体过大）会计入其目标端点，因此端点成功率的分母包括这些失败。

aisix_proxy_requests_total 。描述：所有代理流量（包括模型推理和其他流量）的详细请求结果。。类型：counter 。标签数量：16 个标签

`inbound_protocol` 的值

openai, anthropic, mcp, a2a, realtime, passthrough

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

`stream` 的值

false, true

`is_fallback` 的值

false, true

`outcome` 的值

success, client_error, rate_limited, upstream_error

行为

每次客户端请求采样一次，携带请求最终结束时的状态。请求内部的重试和故障转移不会增加样本，因此这个计数器回答的是「调用方发起了多少请求、各自如何结束」，而不是「网关向上游发起了多少次调用」。

aisix_proxy_failed_requests_total 。描述：结果不为 success 的代理请求子集。。类型：counter 。标签数量：16 个标签

`inbound_protocol` 的值

openai, anthropic, mcp, a2a, realtime, passthrough

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

`stream` 的值

false, true

`is_fallback` 的值

false, true

`outcome` 的值

client_error, rate_limited, upstream_error

client_error 表示除 429 外的 HTTP 400–499；rate_limited 表示所有 HTTP 429（网关限流、预算拒绝或上游自己返回的 429）；其他所有状态均映射为 upstream_error。

aisix_proxy_in_flight_requests 。描述：代理当前正在处理的请求，按标准化端点和入站协议分组。。类型：gauge 。标签数量：2 个标签

`inbound_protocol` 的值

openai, anthropic, mcp, a2a, realtime, passthrough

行为

MCP 请求使用 inbound_protocol="mcp"；聚合网关使用 endpoint="/mcp"，按服务器划分的端点使用 endpoint="/mcp/{server}"。A2A 调用使用 endpoint="/a2a" 和 inbound_protocol="a2a"。获取 Agent Card 使用 endpoint="/a2a/{agent}/.well-known/agent-card.json"；1.7.1 及更早版本将其报告为 endpoint="/a2a"。

标准化为 endpoint="/passthrough_route" 的请求使用 inbound_protocol="passthrough"。

PromQL 示例

sum(aisix_proxy_in_flight_requests) by (endpoint, inbound_protocol)

aisix_proxy_client_cancelled_requests_total 。描述：调用方在网关发送响应头前断开连接的请求。。类型：counter 。标签数量：4 个标签

行为

这些请求不会产生正常结果，因此不会出现在其他请求计数器中。网关会在此处记录它们，并在访问日志中以状态码 499 记录。

该指标速率上升通常意味着调用方在等待首个 Token 时放弃。可按 model 拆分该序列，并与同一模型的 aisix_llm_time_to_first_token_seconds 对比。

model 是调用方请求的模型，Provider Key 标签标识请求当时正在等待的目标。若调用方在网关解析出它们之前就断开连接（例如仍在上传请求体时），这三个标签均为 unknown。

本指标刻意不包含其他请求计数器的调用方身份、状态码和结果标签。被取消的请求没有状态码，通常也没有团队或用户信息，这些维度在每个样本上都会是 unknown。

调用方在响应头发送后断开连接的情况不计入此处。该请求已经产生正常结果和用量事件。

PromQL 示例

sum(rate(aisix_proxy_client_cancelled_requests_total[5m])) by (endpoint, model)

aisix_proxy_request_body_limit_rejections_total 。描述：因超过 proxy.request_body_limit_bytes 而被拒绝的请求，按网关结束读取被拒绝请求体的方式分组。。类型：counter 。标签数量：3 个标签

`inbound_protocol` 的值

openai, anthropic, mcp, a2a, realtime, passthrough

`outcome` 的值

completed, cap_reached, timeout, client_read_error

completed 表示调用方发送了声明的完整请求体，因此可以读取 413 响应。cap_reached 和 timeout 表示网关先停止接收请求体；client_read_error 表示调用方在发送请求体时断开连接。这三种情况下，调用方通常会看到连接关闭，而不是收到响应。

行为

网关会读取并丢弃被拒绝请求的请求体，以便调用方在同一连接上接收 413。该读取操作有上限，outcome 用于报告其结束方式。

除 completed 外，任何结果的占比上升都表示调用方看到的是连接关闭，而不是 413 响应。匹配的 aisix::body_limit 日志条目会记录同一 request_id 的声明大小、配置上限和已读取字节数。

这里只统计声明的 Content-Length 超过上限的请求。采用分块传输且超过上限的请求会在读取时被拒绝，没有可比的 outcome，并以状态码 413 出现在 aisix_requests_total 中。

PromQL 示例

sum(rate(aisix_proxy_request_body_limit_rejections_total[5m])) by (endpoint, inbound_protocol, outcome)

aisix_auth_decisions_total 。描述：API Key、JWT 和缺少凭证路径上的调用方身份认证决策。。类型：counter 。标签数量：3 个标签

`method` 的值

api_key, jwt, none

`result` 的值

allowed, denied

行为

允许请求的 reason 为 none。被拒绝请求使用有限集合中的原因，例如 missing_credentials、unknown_key、key_expired、jwt_bad_signature、jwt_untrusted_issuer 或 jwt_identity_unmapped。

PromQL 示例

sum(rate(aisix_auth_decisions_total{result="denied"}[5m])) by (method, reason)

延迟指标

检查单个网关的延迟，或跨网关实例聚合直方图分桶。

指标条目：6

延迟聚合与标签

跨网关实例的服务级仪表盘和告警应使用直方图，因为可在调用 histogram_quantile() 前聚合其 _bucket、_sum 和 _count 序列。摘要用于检查单个网关实例预先计算的分位数。摘要分位数无法跨实例聚合，因此不要对其取平均值。

每个直方图都有自己的分桶边界，因为两种分布不同：端到端延迟从毫秒级开始，而首个 Token 时间不可能快于生成 Token 的上游。两组边界均可配置。env_id 是已配置的环境 ID：AISIX Enterprise 和 AISIX Cloud 会为托管网关设置它，通过 etcd 配置的 AISIX OSS 网关也可以显式设置；未设置时其值为 unknown。status_class 为 2xx、3xx、4xx、5xx 或 other。为控制分桶序列数量，不包含按密钥和按用户的标签；这些维度请使用用量分析。

两个耗时摘要、aisix_llm_time_to_first_token_seconds 和两个直方图，在 observability.metrics.labels 中加入该指标族的标签列表后，还支持 api_key_name 和 team_name，即认证所用 API Key 及其团队的显示名称。二者都不是默认标签。没有显示名称的 API Key、或网关尚未收到其名称的团队，报告为 unknown；重命名会产生新的序列。1.5.0 及更早版本不输出该标签。

aisix_request_duration_seconds 。描述：兼容性序列中各代理端点的请求持续时间。流式 HTTP 响应记录整个流，并以流结束时的状态记录；1.5.0 及更早版本只记录到响应开始为止。realtime 记录 WebSocket 会话关闭前的完整持续时间。。类型：summary 。标签数量：3 个标签

行为

摘要分位数由各 AISIX 实例计算，无法跨实例聚合。

aisix_llm_request_duration_seconds 。描述：模型推理端点的详细请求持续时间。流式 HTTP 响应记录整个流，并以流结束时的状态记录；1.5.0 及更早版本只记录到响应开始为止。realtime 记录 WebSocket 会话关闭前的完整持续时间。。类型：summary 。标签数量：15 个标签

`inbound_protocol` 的值

openai, anthropic, realtime, passthrough

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

`stream` 的值

false, true

`outcome` 的值

success, client_error, rate_limited, upstream_error

aisix_proxy_request_duration_seconds 。描述：所有代理流量的详细请求持续时间。流式 HTTP 响应记录整个流，并以流结束时的状态记录；1.5.0 及更早版本只记录到响应开始为止。realtime 记录 WebSocket 会话关闭前的完整持续时间。。类型：summary 。标签数量：15 个标签

`inbound_protocol` 的值

openai, anthropic, mcp, a2a, realtime, passthrough

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

`stream` 的值

false, true

`outcome` 的值

success, client_error, rate_limited, upstream_error

aisix_llm_time_to_first_token_seconds 。描述：每个流式响应到首个流式帧的时间，包括聊天补全、消息和响应，流式音频转录和翻译，流式 A2A 调用，以及透传路由的流。side 标签（1.4.0 及更早版本不发射）区分上游区间与客户端实际等待的区间。。类型：summary 。标签数量：13 个标签

`side` 的值

upstream, downstream

upstream 是从服务该请求的那次尝试开始，到上游第一个帧（任意类型）的时间。downstream 是客户端实际等待的时间：从网关收到请求，到写给客户端的第一个帧。始终输出，标签选择无法删除它。1.4.0 及更早版本不发射该标签，它们只记录上游区间，且不带 side 标签。

`inbound_protocol` 的值

openai, anthropic, a2a, passthrough

1.7.1 及更早版本不发射 a2a。

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

行为

1.4.0 及更早版本不发射 side 标签。不按 side 过滤的查询会混合两个区间，因此查看上游视角时请使用 side!="downstream"。不要使用 side="upstream"：它匹配不到 1.4.0 及更早版本网关的任何序列，会在混合版本的集群中悄悄漏掉这些网关。

downstream 区间涵盖请求解析、输入安全护栏、失败的尝试及其退避等待，以及输出安全护栏的扣留。对于首次尝试即成功的请求，downstream 减去 upstream 就是网关侧的工作，通常是安全护栏；对于发生过重试的请求，差值还包含之前的尝试。

downstream 观测是 upstream 观测的子集。在首个帧到达客户端之前被输出安全护栏阻断的流，或在扣留期间被放弃的流，只会记录 upstream 观测。

在非 Anthropic 上游的 /v1/messages 和聊天协议上游的 /v1/responses 上，客户端收到的第一个帧是第一个携带内容的事件。这时 downstream 区间还包含等待该事件的时间，对推理型上游而言就是它的思考时间。

透传路由的流以 endpoint="/passthrough_route" 记录：被 AISIX 识别出协议的回复（1.6.0 及更早版本不记录），以及计时到首个字节帧的不透明中继（1.7.1 及更早版本不记录）。

流式音频转录和翻译，以及流式 A2A 调用（endpoint="/a2a"），1.7.1 及更早版本不记录。非流式响应不会在此记录；/v1/audio/speech 的分块音频正文不是 Token 流，同样不记录；realtime 会话也不记录。

aisix_request_e2e_latency_seconds 。描述：请求指标所统计的每个请求的端到端延迟，包括完整的流式传输时长，realtime 会话除外。。类型：histogram 。标签数量：7 个标签

`side` 的值

upstream, downstream

downstream 是该标签出现之前本直方图一直记录的客户端感知延迟。upstream 是产生该响应的那次尝试的上游耗时，与该尝试的用量事件字段 upstream_latency_ms 是同一个数值。始终输出，标签选择无法删除它。1.4.0 及更早版本不发射该标签，它们只记录 downstream 数值，且不带 side 标签。

`status_class` 的值

2xx, 3xx, 4xx, 5xx, other

`streaming` 的值

false, true

行为

默认分桶范围为 5 毫秒到 600 秒，可通过 observability.metrics.buckets.request_e2e_latency 配置。较低边界用于记录缓存命中和分发前被拒绝的请求等快速响应。跨网关实例计算百分位数前，请先聚合 _bucket 序列。

downstream 一侧在所有记录请求指标的路由上记录，endpoint 相同：模型端点、/v1/models、OAuth 发现文档、MCP、A2A 及其 Agent Card、文件、批处理和微调路由，以及透传路由，包括在认证阶段或下发之前被拒绝的请求。/v1/realtime 例外：WebSocket 会话没有可计时的请求与响应。1.7.1 及更早版本只记录聊天补全、消息、响应、A2A 调用，以及协议被识别为这三种之一的透传路由请求。

每个请求只观测一次。非流式请求和失败请求在处理程序返回时记录。流式请求在流结束时记录，包括客户端取消的情况；取消的流记录 499 和截至取消时的时长，上游中断或超时的流记录其 502 或 504。在响应头发出之前就断开的调用方只计入 aisix_proxy_client_cancelled_requests_total，不在此记录。/v1/videos/:id/content 在视频正文转发给客户端完毕时记录，状态为其响应头的状态。1.5.0 及更早版本对多数被取消或失败的 chat、messages、responses 流记录 2xx 状态类。

A2A 调用使用 endpoint="/a2a"，记录 Agent 调用的完整时长，包含完整的流；被放弃的 A2A 流在 4xx 状态类中记录为 499。1.7.1 及更早版本对已进入 A2A 统计、但在下发之前被拒绝的调用记录零时长，在进入 A2A 统计之前就被拒绝的调用则不记录。

1.4.0 及更早版本不发射 side 标签。上述观测均为 side="downstream"。不按 side 过滤的查询会混合两侧，上游样本会拉低其百分位数，因此查看客户端感知延迟时请使用 side!="upstream"：它同样能匹配 1.4.0 及更早版本网关不带标签的序列。这与 TTFT 指标相反，TTFT 的上游视角使用 side!="downstream"。

每个请求最多记录一次 side="upstream" 观测，除 side 外其标签与 downstream 观测相同。它测量产生该响应的那次尝试，从尝试开始直到上游完成：完整收到响应，或者对流式请求而言上游流结束。只要那次尝试到达了上游就会记录，包括上游错误和超时；在 /a2a 上，这次尝试就是对 Agent 的调用。缓存命中、在下发之前失败的请求、合议模型，以及不报告任何尝试的路由（例如 /v1/models、发现文档、视频状态查询和内容下载请求）只记录 downstream 一侧。1.7.1 及更早版本对 A2A 调用也只记录 downstream 一侧。更早失败的尝试及其重试退避只包含在 downstream 数值中。

PromQL 示例

histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_e2e_latency_seconds_bucket{side!="upstream"}[5m]))
)

aisix_request_ttft_seconds 。描述：每个流式响应到首个流式帧的时间，包括聊天补全、消息和响应，流式音频转录和翻译，流式 A2A 调用，以及透传路由的流。side 标签（1.4.0 及更早版本不发射）区分上游区间与客户端实际等待的区间。。类型：histogram 。标签数量：7 个标签

`side` 的值

upstream, downstream

`status_class` 的值

2xx, 3xx, 4xx, 5xx, other

`streaming` 的值

true

行为

在 upstream 一侧，即使上游首帧不携带任何可见的生成输出——例如仅包含角色的起始帧或 Anthropic 的 message_start 事件——它也会停止计时。内容帧、推理帧和工具调用帧同样会停止计时。

downstream 观测是 upstream 观测的子集。在首个帧到达客户端之前被输出安全护栏阻断的流，或在扣留期间被放弃的流，只会记录 upstream 观测。

默认分桶范围为 50 毫秒到 300 秒，可通过 observability.metrics.buckets.request_ttft 配置。当附近的模型服务器可以在 50 毫秒内生成输出时，请降低起始边界。只使用托管服务提供方的部署可以提高下限，移除始终为空的分桶。

PromQL 示例

# 上游 P90 TTFT；同样匹配 1.4.0 及更早版本的网关
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_ttft_seconds_bucket{side!="downstream"}[5m]))
)

# 客户端侧 P90 TTFT，用于与上游 P90 对比
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_ttft_seconds_bucket{side="downstream"}[5m]))
)

用量与成本指标

测量 Token 用量和标准化客户端用量。

指标条目：9

哪些端点报告 Token

所有从上游接收 Token 数量的端点都会在此记录，包括聊天补全、补全、消息、响应、向量嵌入、重排序、/v1/systemone 和 /v1/decisions、音频转录和翻译路由、图像生成和编辑，以及 realtime 会话。

/a2a 记录网关对 message/send 和 message/stream 调用消息文本自行统计的 Token 数，即其用量事件以 usage_estimated: true 标记的数值，处理方式与聊天补全记录的估算值相同，且只在 Agent 实际收到调用时记录。1.7.1 及更早版本不发射。

/v1/messages/count_tokens 不消耗 Token，不在此记录；MCP 工具调用、不透明的透传中继、文件和微调路由同样不记录。批处理结果也不记录：已完成批处理的用量事件仍携带其 Token，但没有任何机制能保证一个批处理在多个网关副本和重启之间只被统计一次。

透传路由同样会在此以 endpoint="/passthrough_route" 记录 Token：适用于协议被 AISIX 识别为上述端点之一（聊天、Anthropic Messages、响应、补全、向量嵌入、图像生成或编辑、重排序）的请求，并按该端点的方式读取。其 model 是请求正文中的 model 归一到已配置模型名称后的值，或 unresolved。1.6.0 及更早版本不发射。

有两个模型推理端点不会报告 Token，因为其计费方式不同：/v1/audio/speech 按输入字符计费，/v1/videos 按视频计费。两者仍计为请求，因此只能在同一 endpoint 内用 Token 总数除以请求数，不能跨全部端点计算。

逐请求 Token 序列（三个 aisix_llm_*_tokens_total 计数器）使用与详细请求计数器相同的标签，因此查询可基于 endpoint、model、provider 和调用方身份标签关联 Token 用量与请求结果。另两个指标的标签不同：aisix_tokens_consumed_total 仅按 provider 和 model 标记；aisix_llm_tokens_by_client_total 仅按 client_type、model 和 token_type 标记。

携带调用方身份的 Token 和缓存 Token 计数器还支持 api_key_name 和 team_name，即认证所用 API Key 及其团队的显示名称。二者都不是默认标签：需将其加入 observability.metrics.labels 中该指标族的标签列表。没有显示名称的 API Key、或网关尚未收到其名称的团队，报告为 unknown；重命名会产生新的序列。1.5.0 及更早版本不输出该标签。

另有三个计数器单独统计上游服务商用自身提示词缓存提供的 Token。它们与上述 Token 计数器使用相同的标签，且仅在取值非零时才创建序列，因此不报告缓存明细的服务商不会产生任何序列。它们描述的是**上游服务商**的缓存，而不是 AISIX 响应缓存——后者是缓存指标中的 aisix_cache_requests_total，两者互不相关。

各服务商对缓存读取采用两种不同的计量口径，因此读取侧有两个计数器而非一个。aisix_llm_cached_input_tokens_total 对应 OpenAI 口径：缓存命中的 Token 本身就属于上报的提示词 Token，因此已经包含在 aisix_llm_input_tokens_total 之内。aisix_llm_cache_read_input_tokens_total 和 aisix_llm_cache_creation_input_tokens_total 对应 Anthropic 口径：它们与输入 Token 并列上报而非包含其中，因此位于 aisix_llm_input_tokens_total 之外、aisix_llm_total_tokens_total 之内。

把两种口径分开正是跨协议查询能够成立的原因：请求实际消耗的输入为 aisix_llm_input_tokens_total + aisix_llm_cache_read_input_tokens_total + aisix_llm_cache_creation_input_tokens_total，其中由缓存提供的部分为 aisix_llm_cached_input_tokens_total + aisix_llm_cache_read_input_tokens_total。这两个表达式对任一服务商口径都成立。参见计算提示词缓存命中率。

aisix_tokens_consumed_total 。描述：所有报告 Token 用量的端点的 Token 总数，属于覆盖范围最广的兼容性序列。。类型：counter 。标签数量：2 个标签

aisix_llm_input_tokens_total 。描述：AISIX 归因到该请求的输入 Token 数。对于模型端点，AISIX 会将服务提供方上报的用量标准化，并估算缺失的数量。Dev 版本根据请求文本估算 A2A 输入 Token；1.7.1 版本不发射 A2A Token 计数器。。类型：counter 。标签数量：12 个标签

`inbound_protocol` 的值

openai, anthropic, realtime, passthrough, a2a

1.7.1 及更早版本不发射 a2a。

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

aisix_llm_output_tokens_total 。描述：AISIX 归因到该请求的输出 Token 数。对于模型端点，AISIX 会将服务提供方上报的用量标准化，并估算缺失的数量。Dev 版本根据响应文本估算 A2A 输出 Token；1.7.1 版本不发射 A2A Token 计数器。。类型：counter 。标签数量：12 个标签

`inbound_protocol` 的值

openai, anthropic, realtime, passthrough, a2a

1.7.1 及更早版本不发射 a2a。

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

aisix_llm_total_tokens_total 。描述：AISIX 归因到该请求、包含缓存 Token 的总数。对于模型端点，AISIX 会将服务提供方上报的用量标准化，并估算缺失的数量。Dev 版本根据请求和响应文本估算 A2A Token 总数；1.7.1 版本不发射 A2A Token 计数器。。类型：counter 。标签数量：12 个标签

`inbound_protocol` 的值

openai, anthropic, realtime, passthrough, a2a

1.7.1 及更早版本不发射 a2a。

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

aisix_llm_cached_input_tokens_total 。描述：上游用其提示词缓存提供、并计入提示词 Token 数量的输入 Token。。类型：counter 。标签数量：12 个标签

`inbound_protocol` 的值

openai, anthropic, realtime, passthrough

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

行为

OpenAI 计量口径：OpenAI 及 OpenAI 兼容服务商的 prompt_tokens_details.cached_tokens、DeepSeek 的 prompt_cache_hit_tokens、Vertex AI 上 Gemini 的 cachedContentTokenCount。这些 Token 已计入 aisix_llm_input_tokens_total，两者相加会重复计算。

仅在上游报告该字段时记录。AISIX 不会依据响应耗时或提示词相似度推断缓存命中。

aisix_llm_cache_read_input_tokens_total 。描述：上游用其提示词缓存提供、并与输入 Token 数量分开上报的输入 Token。。类型：counter 。标签数量：12 个标签

`inbound_protocol` 的值

openai, anthropic, realtime, passthrough

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

行为

Anthropic 计量口径：Anthropic 的 cache_read_input_tokens 和 Amazon Bedrock 的 cacheReadInputTokens。这些 Token **不**包含在 aisix_llm_input_tokens_total 中，但包含在 aisix_llm_total_tokens_total 中。

aisix_llm_cache_creation_input_tokens_total 。描述：写入上游提示词缓存的输入 Token。。类型：counter 。标签数量：12 个标签

`inbound_protocol` 的值

openai, anthropic, realtime, passthrough

`upstream_protocol` 的值

openai, anthropic, bedrock, vertex, azure-openai, unknown

网关与上游通信所使用的协议，与 inbound_protocol 相互独立。unknown 表示该请求没有选中任何上游——在转发前被拒绝，或是不调用模型的路由。

行为

对应 Anthropic 的 cache_creation_input_tokens 和 Amazon Bedrock 的 cacheWriteInputTokens。与同一口径下的缓存读取一样，这些 Token 位于 aisix_llm_input_tokens_total 之外、aisix_llm_total_tokens_total 之内。

各服务商对缓存写入的计费高于标准输入价格，对缓存读取的计费则远低于标准价格，因此写入远多于读取的工作负载反而比完全不用缓存更贵。将该计数器与 aisix_llm_cache_read_input_tokens_total 对比即可发现这种情况。

aisix_llm_spend_micro_usd_total 。描述：1.7.1 之后已移除：后续版本不再发射。统计支出请以控制面为每个请求记录的费用为准；用量事件仍携带 cost_usd。在 1.7.1 及更早版本中，它是网关仅为 Realtime 会话自行估算的支出，单位为价格所用币种的百万分之一。。类型：counter 。标签数量：12 个标签

`endpoint` 的值

/v1/realtime

`inbound_protocol` 的值

realtime

`upstream_protocol` 的值

openai, azure-openai

行为

observability.metrics.labels 中仍写有该指标族时，后续版本的网关照常启动：忽略该条目，并在启动时输出一次警告。请删除该条目。

aisix_llm_tokens_by_client_total 。描述：所有报告 Token 用量的端点中的 Token 用量，按标准化客户端、请求模型和 Token 类型分组。。类型：counter 。标签数量：3 个标签

`client_type` 的值

openai-python, openai-node, anthropic-python, anthropic-typescript, claude-code, codex, cline, roo-code, kilocode, zoo-code, github-copilot, cursor, opencode, qwen-code, gemini-cli, crush, zed, aider, vercel-ai-sdk, langchain, llamaindex, litellm, curl, python-requests, httpx, aiohttp, okhttp, go-http-client, node, postman, browser, other, unknown

无法识别的 User-Agent 映射为 other；缺少 User-Agent 时映射为 unknown。部署可通过管理员定义的映射规则（observability.metrics.client_type_rules）扩展此集合。完整的 User-Agent 字符串和版本仍会保留在请求日志和用量分析中。

`token_type` 的值

input, output, total

total 包含输入、输出以及 Anthropic 缓存创建和缓存读取 Token。

行为

model 是调用方请求的模型名称，与 aisix_llm_* Token 序列的 model 标签值相同。路由、语义、合议和故障转移分发会保留此别名，而不是报告所选直接模型。

有界的 client_type 白名单可防止客户端可控的 User-Agent 导致 Prometheus 基数无限增长。具体模型别名受已配置模型集合的限制，但通配符别名会记录通过该模式请求的每个具体模型名称。基数很重要时，请限制通配符访问并监控标签增长。

管理员定义的映射规则（observability.metrics.client_type_rules）可对更多客户端进行分类。规则在内置白名单之前匹配，并输出固定且经过验证的标签值，因此标签集合保持有界。

在相同端点范围内跨所有标签聚合后，包含缓存的 total 与 aisix_llm_total_tokens_total 一致。由于两个指标系列使用不同的标签集合，单条序列并不对应；专用客户端类型序列避免为按密钥统计的 Token 序列再增加一个标签维度。

Anthropic 将缓存 Token 与输入 Token 分开报告，因此 total 可能大于 input 与 output 之和。

PromQL 示例

sum by (client_type, model, token_type) (
  rate(aisix_llm_tokens_by_client_total[5m])
)

限流与预算指标

监控每个标签集合的限流拒绝，以及最新配额或预算状态。

指标条目：8

aisix_ratelimit_rejections_total 。描述：在各代理端点上被共享限流闸门拒绝的请求。。类型：counter 。标签数量：3 个标签

`scope` 的值

requests, tokens

并发限制拒绝使用 requests；运行时不会发出单独的 concurrency 值。

`layer` 的值

api_key, model, mcp, policy

行为

policy_id 在 layer="policy" 之外为空；在策略层上，该标签携带已配置的策略 ID。

可通过 observability.metrics.labels 添加 policy_name，即同一策略的配置名称；它不是默认标签。与 policy_id 一样，它在 layer="policy" 之外为空。1.5.0 及更早版本不输出该标签。

限流器背后的共享 Redis 可能在不拒绝任何请求的情况下失败——限流器会静默回退为按副本计数。这类失败由缓存指标中的 aisix_redis_failures_total 统计。

aisix_ratelimit_remaining_requests 。描述：API Key 限流窗口中的剩余请求配额，按 API Key 和模型分组；解析出模型的请求经过配额关卡时刷新。。类型：gauge 。标签数量：2 个标签

行为

在所有于配额关卡之前解析出模型的路由上刷新，无论关卡放行还是拒绝该请求：模型端点、realtime 会话、文件、批处理和微调路由，以及请求正文指定了该路由提供商下已配置模型的透传路由。聊天补全在关卡拒绝时刷新，并在成功响应提交其 Token 后再次刷新。MCP 工具调用、A2A 调用和视频状态查询不解析模型，不会改变它。1.7.1 及更早版本只在聊天补全上刷新。

model 是请求解析到的已配置模型——通配符别名报告的是该行本身（例如 openai/*），而不是调用方发来的具体名称。

在 API Key 被删除、或其报告的模型不再存在之后的数秒内退休为 NaN。用 NaN 而不是 0，是因为 0 在这个仪表上本身就是一个有意义的读数；任何与 NaN 的比较都为假，因此挂在退休序列上的告警会停止触发。对含有退休序列的指标族做聚合，结果同样是 NaN。

可通过 observability.metrics.labels 添加 api_key_name，即 API Key 的显示名称；它不是默认标签，没有显示名称的 API Key 报告为 unknown。重命名 API Key 会产生新的序列，旧序列以同样方式退休。1.5.0 及更早版本不输出该标签。

aisix_ratelimit_remaining_tokens 。描述：API Key 限流窗口中的剩余 Token 配额，按 API Key 和模型分组；解析出模型的请求经过配额关卡时刷新。。类型：gauge 。标签数量：2 个标签

行为

刷新的路由和时机与 aisix_ratelimit_remaining_requests 相同。1.7.1 及更早版本只在聊天补全上刷新。

model 是请求解析到的已配置模型——通配符别名报告的是该行本身（例如 openai/*），而不是调用方发来的具体名称。

aisix_budget_limit_usd 。描述：预算上限（控制面返回的金额；指标名保留 usd）。。类型：gauge 。标签数量：4 个标签

行为

1.6.0 按美元计价；开发版按组织币种计价。开发版的 usd 后缀为保留名称，不表示固定使用美元。

删除某把 Key 的预算不会把这个仪表置零——它会保留最后一次的预算值，这正是查询需要加上 aisix_budget_details_present == 1 条件的原因。

在 API Key 被删除、或被改绑到其他团队或成员之后的数秒内退休为 NaN。用 NaN 而不是 0，是因为 0 在这个仪表上本身就是一个有意义的读数；任何与 NaN 的比较都为假，因此挂在退休序列上的告警会停止触发。对含有退休序列的指标族做聚合，结果同样是 NaN。

可通过 observability.metrics.labels 添加 api_key_name 和 team_name，即 API Key 及其团队的显示名称；二者都不是默认标签，无法解析的名称报告为 unknown。重命名 API Key 或团队会产生新的序列，旧序列以同样方式退休。1.5.0 及更早版本不输出该标签。

aisix_budget_spent_usd 。描述：已用预算（控制面返回的金额；指标名保留 usd）。。类型：gauge 。标签数量：4 个标签

行为

1.6.0 按美元计价；开发版按组织币种计价。开发版的 usd 后缀为保留名称，不表示固定使用美元。

删除某把 Key 的预算不会把这个仪表置零——它会保留最后一次的预算值，这正是查询需要加上 aisix_budget_details_present == 1 条件的原因。

aisix_budget_remaining_usd 。描述：剩余预算（控制面返回的金额；指标名保留 usd）。。类型：gauge 。标签数量：4 个标签

行为

1.6.0 按美元计价；开发版按组织币种计价。开发版的 usd 后缀为保留名称，不表示固定使用美元。

删除某把 Key 的预算不会把这个仪表置零——它会保留最后一次的预算值，这正是查询需要加上 aisix_budget_details_present == 1 条件的原因。

aisix_budget_reset_seconds 。描述：距离预算周期重置的秒数。。类型：gauge 。标签数量：4 个标签

行为

删除某把 Key 的预算不会把这个仪表置零——它会保留最后一次的预算值，这正是查询需要加上 aisix_budget_details_present == 1 条件的原因。

aisix_budget_details_present 。描述：是否已填充预算详情。。类型：gauge 。标签数量：4 个标签

`指标值` 的值

0, 1

1 表示存在预算详情；0 表示预算详情已清除。

行为

可通过 observability.metrics.labels 添加 api_key_name 和 team_name，即 API Key 及其团队的显示名称；二者都不是默认标签，无法解析的名称报告为 unknown。重命名 API Key 或团队会产生新的序列。1.5.0 及更早版本不输出该标签。

缓存指标

按策略衡量响应缓存的效果，并关注语义层的向量嵌入与存储健康状况。

指标条目：5

缓存命中率

每个被已启用缓存策略覆盖、且后端可用的请求都会记录一次 aisix_cache_requests_total。没有匹配策略或后端不可用的请求不计入——闸门从未打开——因此该系列衡量的是策略效果，而不是总流量。

按策略计算命中率：sum by (policy) (rate(aisix_cache_requests_total{outcome=~"hit_exact|hit_semantic"}[5m])) / sum by (policy) (rate(aisix_cache_requests_total[5m]))。按 outcome 拆分可以看出语义层在精确匹配之上贡献了多少。

语义层的失败会退化为普通未命中，仅凭结果计数器无法区分损坏的向量嵌入模型或存储与健康的低命中率。对 aisix_cache_semantic_embedding_failures_total 和 aisix_cache_semantic_store_failures_total 设置告警来区分二者。

aisix_cache_requests_total 。描述：按策略名称和结果统计的缓存合格请求，当匹配的已启用策略与可用后端打开缓存闸门时，每个请求计数一次。。类型：counter 。标签数量：2 个标签

`outcome` 的值

hit_exact, hit_semantic, miss, bypass

bypass 表示调用方发送了 Cache-Control: no-cache，跳过了读取路径。no-store 会保留读取路径，因此记录为普通的命中或未命中，并且只在未命中后禁止写入。

aisix_cache_semantic_embedding_seconds 。描述：语义层向量嵌入调用的延迟，按策略统计。无固定桶的摘要系列。。类型：summary 。标签数量：1 个标签

`cause` 的值

resolve, embed

resolve（向量嵌入模型缺失或不是向量嵌入模型）按合格请求计数一次，包括随后命中精确层的请求；embed（服务提供方调用失败或超时）按向量嵌入调用计数。

aisix_cache_semantic_store_failures_total 。描述：语义存储的操作失败，按操作统计。进程内存储不会失败；共享（Redis）存储可能失败。失败退化为普通未命中。。类型：counter 。标签数量：2 个标签

`op` 的值

lookup, store

aisix_redis_failures_total 。描述：对 Redis 后端存储的失败操作，每次操作失败计数一次。它覆盖所有以 Redis 为后端的子系统——共享限流器、精确响应缓存和语义缓存——因为一套部署通常把它们指向同一个 Redis。1.1.0 及更早版本不发射该指标。。类型：counter 。标签数量：1 个标签

`operation` 的值

ratelimit_acquire, ratelimit_commit, ratelimit_peek, ratelimit_release, ratelimit_add_tokens, cache_get, cache_put, semantic_acquire, semantic_index, semantic_lookup, semantic_store

取值同时标明子系统和具体调用，因此即使限流器与各类缓存共用一个 Redis，也能分辨出是哪个存储在退化。

行为

这些失败在设计上都是静默降级——共享限流器回退为按副本计数，缓存读取变成未命中——因此该计数器是唯一能反映这种降级的指标。其中大多数同时也会记录日志；只有分离出去的 ratelimit_release 和 ratelimit_add_tokens 操作没有日志，该计数器是它们唯一的痕迹。

部署指标

监控每个目标模型的表现：上游尝试及其结果、目标之间的回退，以及目标是否仍参与轮转。

指标条目：7

统计的是尝试而非请求

这些计数器每次上游**尝试**采样一次，且每个样本归属于被尝试的目标，而不是调用方指定的模型组。一次客户端请求若在三个目标之间故障转移，在这里是三个样本，在请求指标中是一个样本。用本族回答「哪个目标在失败」，用请求族回答「调用方经历了什么」。

只统计真正到达上游的尝试。被网关自行拒绝的尝试——目标超出其自身限流，或其凭据、端点在发送任何内容之前就未通过校验——从未产生上游响应，因此不会出现在这里，但仍会出现在用量日志中。这样配置错误就不会被读成目标不健康。

模型端点下发的每次上游尝试都会记录，无论目标是直连模型还是模型组中的目标，包括 /v1/videos 提交。视频状态查询和内容下载请求、realtime 会话（完成的 WebSocket 升级计为成功），以及文件、批处理和微调路由，也会在此记录其上游调用；1.7.1 及更早版本不记录这些。MCP 工具调用、A2A 调用和透传路由不调用已配置模型，不在此记录。

两个回退计数器来自模型端点在目标之间的故障转移。realtime 会话、视频状态查询和内容下载请求，以及文件、批处理和微调路由只调用一个目标，从不记录回退。

aisix_deployment_requests_total、aisix_deployment_success_responses_total、aisix_deployment_failure_responses_total 和 aisix_deployment_cooled_down_total 在 observability.metrics.labels 中加入该指标族的标签列表后，还支持 provider_key_name，即提供商密钥的显示名称；它在这些指标上不是默认标签，重命名会产生新的序列。aisix_deployment_state 不支持该标签：该 Gauge 只在目标健康状态变化时写入，重命名后的密钥在下一次状态变化之前会一直报告旧名称。1.5.0 及更早版本不输出该标签。

aisix_deployment_requests_total 。描述：下发到某个目标模型的上游尝试次数，不论结果如何。。类型：counter 。标签数量：4 个标签

PromQL 示例

sum(rate(aisix_deployment_requests_total[5m])) by (model)

aisix_deployment_success_responses_total 。描述：目标模型成功响应的上游尝试次数。。类型：counter 。标签数量：4 个标签

行为

对于流式响应，尝试在上游流建立时即计为成功。此后中断的流不会在这里重新归类。

aisix_deployment_failure_responses_total 。描述：在目标模型处失败的上游尝试次数，包含随后被回退救回的那些失败。。类型：counter 。标签数量：4 个标签

PromQL 示例

sum(rate(aisix_deployment_failure_responses_total[5m])) by (model)
  / sum(rate(aisix_deployment_requests_total[5m])) by (model)

aisix_routing_successful_fallbacks_total 。描述：在先前目标失败后，成功处理了该请求的回退尝试次数。。类型：counter 。标签数量：2 个标签

行为

model 是调用方所请求的名称，即模型组名称。fallback_model 是网关转向的目标。

aisix_routing_failed_fallbacks_total 。描述：同样失败的回退尝试次数。。类型：counter 。标签数量：2 个标签

行为

被第二个回退目标救回的请求，会在这里贡献一个样本，同时在成功回退族中贡献一个样本。

aisix_deployment_state 。描述：目标模型是否参与轮转。。类型：gauge 。标签数量：4 个标签

`指标值` 的值

0, 2

0 表示健康。2 表示目标因正在冷却或后台健康检查失败而退出轮转。

aisix_deployment_cooled_down_total 。描述：目标模型进入冷却的次数。。类型：counter 。标签数量：4 个标签

安全护栏指标

跟踪所有端点上各安全护栏的执行延迟和结果，以及聚合阻断和 fail-open 绕过。

指标条目：3

安全护栏执行延迟

每次计时的安全护栏执行都会记录一条 aisix_guardrail_latency_seconds 观测。安全护栏通常在每个适用阶段执行一次；流式窗口扫描可以为一条响应记录多次输出执行。该直方图使用可配置的分桶，默认范围为 1 毫秒到 30 秒，因此可通过 histogram_quantile 计算各安全护栏的 P50/P95/P99。

kind 标签标识所配置的安全护栏实现；result 标签用于区分 fail-open 绕过（bypassed，失败标签位于 error_type 中）与策略决策。fail-closed 的评估失败会显示为 blocked；请按 error_type 过滤，把它与策略命中区分开。

_count 序列同时也可用作各安全护栏的执行计数器：sum by (guardrail, result) (rate(aisix_guardrail_latency_seconds_count[5m])) 无需单独的计数器即可提供执行率和阻断率。

聚合计数器覆盖所有受安全护栏保护的端点，但统计单位不同。aisix_guardrail_blocks_total 统计被拒绝的请求，aisix_guardrail_bypasses_total 统计绕过事件，其中包括在任何安全护栏成员执行之前由网关发起的放行。它们不包含安全护栏、种类和阶段标签；需要计时执行的这些维度时，请使用直方图的 _count 序列。

aisix_guardrail_latency_seconds 。描述：所有端点中一次计时的安全护栏执行所经历的实际时间。guardrail 是配置的安全护栏名称。。类型：histogram 。标签数量：6 个标签

`kind` 的值

keyword, pii, aliyun_ai_guardrail, aliyun_text_moderation, azure_content_safety, azure_content_safety_text_moderation, bedrock, lakera, openai_moderation, presidio, semantic, custom

keyword 和 pii 在进程内运行。semantic 调用配置的向量嵌入模型，custom 运行配置的脚本，其余种类调用审核服务。

`phase` 的值

input, output

`result` 的值

allowed, blocked, masked, bypassed, would_block, would_mask, would_mask_unsupported

bypassed 表示评估失败后 fail-open；fail-closed 的评估失败记录为 blocked。would_block/would_mask/would_mask_unsupported 来自配置为 enforcement_mode: monitor 的安全护栏。would_mask_unsupported 表示脱敏规则在无法改写内容的路由（例如透传路由）上命中；强制执行的安全护栏遇到同样的命中时记录为 allowed，因为内容已不经修改地放行。1.4.0 及更早版本不发射 would_mask_unsupported，它们把这类命中记录为 would_mask。

`error_type` 的值

none, aliyun_5xx, aliyun_config_error, aliyun_bad_response, aliyun_throttled, aliyun_timeout, azure_cs_5xx, azure_cs_config_error, azure_cs_throttled, azure_cs_timeout, bedrock_5xx, bedrock_throttled, bedrock_timeout, bedrock_too_large, lakera_5xx, lakera_config_error, lakera_throttled, lakera_timeout, lakera_too_large, openai_moderation_5xx, openai_moderation_config_error, openai_moderation_throttled, openai_moderation_timeout, openai_moderation_too_large, presidio_5xx, presidio_config_error, presidio_throttled, presidio_timeout, presidio_too_large, custom_timeout, custom_script_error, custom_engine_error, custom_no_verdict, custom_bad_verdict, custom_unknown_action, semantic_embed_unresolved, semantic_embed_timeout, semantic_embed_upstream

当评估失败产生 result="blocked"、result="bypassed" 或监控模式下的 result="would_block" 时，设置为有界失败标签；其他情况为 none。bypassed 使用的取值同样用于 aisix_guardrail_bypasses_total{reason}。该计数器还会为网关自身发起、不产生计时直方图观测的放行使用 unscannable_body 和 output_buffer_exceeded。

行为

默认分桶：0.001、0.0025、0.005、0.01、0.025、0.05、0.1、0.25、0.5、1、2.5、5、10 和 30 秒，可通过 observability.metrics.buckets.guardrail_latency 配置。

监控模式执行会在请求继续处理的同时记录 would_block / would_mask，因此可以在实施策略前评估分阶段策略的规模。

通过同步逐字段操作执行的 PII 和关键词脱敏不会计入该序列；其进程内耗时以微秒计。

aisix_guardrail_blocks_total 。描述：在所有端点上被输入或输出安全护栏强制措施拒绝的请求数，包括安全护栏成员执行前因流式输出缓冲区溢出等原因触发的 fail-closed 路径。。类型：counter 。标签数量：无标签

`reason` 的值

aliyun_5xx, aliyun_config_error, aliyun_bad_response, aliyun_throttled, aliyun_timeout, azure_cs_5xx, azure_cs_config_error, azure_cs_throttled, azure_cs_timeout, bedrock_5xx, bedrock_throttled, bedrock_timeout, bedrock_too_large, lakera_5xx, lakera_config_error, lakera_throttled, lakera_timeout, lakera_too_large, openai_moderation_5xx, openai_moderation_config_error, openai_moderation_throttled, openai_moderation_timeout, openai_moderation_too_large, presidio_5xx, presidio_config_error, presidio_throttled, presidio_timeout, presidio_too_large, custom_timeout, custom_script_error, custom_engine_error, custom_no_verdict, custom_bad_verdict, custom_unknown_action, semantic_embed_unresolved, semantic_embed_timeout, semantic_embed_upstream, unscannable_body, output_buffer_exceeded

unscannable_body 和 output_buffer_exceeded 由网关自身发起：前者是 AISIX 无法读取的内容，后者是被保留的流在 on_buffer_exceeded: fail_open 下未经扫描放行。1.4.0 及更早版本不发射 output_buffer_exceeded，它们不把这种放行计为绕过。

A2A 指标

按调用到的 Agent 和调用的操作来度量 Agent-to-Agent 流量。

指标条目：4

Agent 与操作标签

agent 是已注册的 A2A Agent，operation 是调用方实际调用的规范化操作。A2A 0.3 和 1.0 会把同一个操作拼成两种写法，因此 AISIX 记录规范化形式；同时对接两个版本的部署仍然会聚合为同一条序列。无法识别的方法归为 unknown。

任务 ID、上下文 ID 和 JSON-RPC 请求 ID 有意不作为标签。正是它们让单次调用可追踪，也正因如此它们不能做标签值；请到用量事件和链路追踪中查找。

aisix_a2a_requests_total 与 aisix_proxy_requests_total{endpoint="/a2a"} 的数字并不一致，这是有意为之。在 Agent 解析出来之前就被拒绝的调用没有可归属的 Agent，只会计入 proxy 系列。调用方中途放弃的流在两个系列中都是 499；1.5.0 及更早版本在 proxy 系列中把它计为 2xx，因为响应是以 200 开始的。看 Agent 健康度用这个系列，看路由流量用 proxy 系列。

对于流式 A2A，aisix_proxy_request_duration_seconds 记录完整的流；1.5.0 及更早版本只记录到响应开始为止的时间。aisix_request_e2e_latency_seconds{endpoint="/a2a"} 记录 Agent 调用的完整时长，包含完整的流，其 side="upstream" 序列记录对 Agent 的调用（1.7.1 及更早版本不记录）。获取 Agent Card 计入其单独的 endpoint="/a2a/{agent}/.well-known/agent-card.json"。

aisix_a2a_requests_total 。描述：按调用到的 Agent、调用的规范化操作和状态类别统计的 A2A 调用数。。类型：counter 。标签数量：3 个标签

行为

与用量事件在同一处记录，因此被计入用量的调用一定也被计入指标。

PromQL 示例

sum by (agent, operation) (
  rate(aisix_a2a_requests_total{status!="2xx"}[5m])
)

aisix_a2a_ttfb_seconds 。描述：流式 A2A 调用中，上游 Agent 发出首个流式事件的耗时。。类型：histogram 。标签数量：2 个标签

行为

之所以按「事件」而非「Token」命名，是因为 Agent 流传输的是任务更新而不是 Token。默认分桶与 aisix_request_ttft_seconds 相同，可通过 observability.metrics.buckets.a2a_ttfb 配置。

仅在至少产生一个事件的流式操作上记录。

PromQL 示例

histogram_quantile(
  0.90,
  sum by (le, agent) (rate(aisix_a2a_ttfb_seconds_bucket[5m]))
)

aisix_a2a_stream_events_total 。描述：流式 A2A 调用中向下游转发的事件数。。类型：counter 。标签数量：2 个标签

行为

除以流式操作上的 aisix_a2a_requests_total，即为每次调用的事件数——可以看出某个 Agent 有多「话密」，以及这一点是否发生了变化。message/stream 和 tasks/resubscribe 都是流式操作，分母要同时包含两者，否则比值会偏高。

PromQL 示例

sum by (agent) (rate(aisix_a2a_stream_events_total[5m]))
/
sum by (agent) (
  rate(aisix_a2a_requests_total{operation=~"message/stream|tasks/resubscribe"}[5m])
)

aisix_a2a_task_state_total 。描述：按 Agent 最后上报的任务状态统计的 A2A 调用数，已归一为规范定义的状态集合加 unknown。。类型：counter 。标签数量：2 个标签

行为

这是按每次调用「结束时」的状态累加的计数器，因此应当按速率来读，而不是当作实时积压量：任务后续状态变化不会减少之前的样本，而用 tasks/get 轮询同一个任务时每次轮询都会再上报一次状态。上游从未应答的调用不会上报状态，也不计入此指标。

PromQL 示例

sum by (agent, state) (rate(aisix_a2a_task_state_total[5m]))

用量事件指标

区分用量事件发送尝试与未能到达控制面的事件——无论是传递队列未接受，还是 worker 未能投递。

指标条目：6

用量事件传递

每次发送尝试的事件要么被传递到控制面，要么计为丢弃。从发送尝试速率中减去丢弃速率，即可计算传递速率。已传递的事件仍可能被控制面拒绝而未被存储，这部分由 aisix_usage_events_rejected_total 统计。

丢弃来自两个环节。队列侧的 reason（sink_disabled、sink_full、sink_closed）统计交接队列从未接受的事件，它们与发送尝试计数器携带相同的 model、provider_key_id 和 provider_key_name 标签，因此该减法在按模型、按 Provider Key 的粒度上同样成立。投递侧的 reason（send_failed、retry_budget_exhausted）统计 worker 已接受、但未能上报到控制面的事件；worker 持有的是事件本身而不是发出该事件的处理器所用的标签集，因此这些样本的 model 和两个 Provider Key 标签均为 unknown，只携带成员这一对标签。所以 发送尝试 = 已传递 + 已丢弃 在总量以及按 user_id/user_name 的粒度上成立，而按模型、按 Provider Key 的减法只覆盖队列侧。

被队列接受不等于已传递。worker 接受事件之后，控制面上报仍可能失败：在控制面表明自己按批次 ID 去重的前提下，worker 会重发失败的批次，并在该批次最早一条事件之后 30 分钟、或 8 次被应答的失败之后放弃，写入 telemetry batch failed (events dropped) 日志。这类丢失按投递侧的 reason 计入 aisix_usage_event_drops_total。导出器链路则是另一条独立的腿——它由同一个发射点供给，而不是接在 worker 之后——同样可能在重试后丢弃；导出器侧的丢失不会增加该计数器，由 aisix_otlp_fanout_drops_total 统计。

status_code 标签为 2xx、3xx、4xx、5xx 或 other，status 则在其旁边携带原始 HTTP 状态码——status 用于定位单一故障模式，status_code 用于按状态族汇总，二者描述的是同一个事件。handler 示例值包括 chat、embeddings、messages 和 mcp。

user_id 是发起请求所用 API Key 所属的组织成员，user_name 是该成员的显示名称；API Key 未绑定成员时二者均为 unknown。两个计数器都携带这两个标签，因此 发送尝试 = 已传递 + 已丢弃 在按成员的粒度上依然成立。由于经 JWT 认证的请求会以其身份解析出的 API Key 运行，一个成员标签即可覆盖该成员使用的全部凭证。名称与 ID 一一对应，因此不会增加新的序列维度。在 1.5.0 及更早版本上，它是控制面上次投影该 API Key 时写入的名称，而非实时查询结果：此后成员改名，这些指标上仍会沿用旧名称，直到该 API Key 因其他原因被再次写入。更新版本的网关从成员自己的名称文档读取该名称，控制面会在成员改名时更新该文档。

model 是调用方请求的模型，并会归一到已配置的模型名称。未能解析出模型的请求报告 unresolved；本身就没有模型的请求——MCP 工具调用、A2A Agent 调用、正文未指定模型的透传请求——报告 unknown。凡是未解析出上游 Provider Key 的情况，两个 Provider Key 标签同样为 unknown。

MCP 工具调用使用 handler="mcp" 和 inbound_protocol="mcp"。其用量事件负载会标识 MCP 服务器和工具；Token 与成本字段为零。

A2A Agent 调用使用 handler="a2a"。该指标将其有界的 inbound_protocol 标签映射为 other，而传递的事件使用 inbound_protocol="a2a"，并标识 Agent 名称和 JSON-RPC 方法。网关会根据消息文本估算输入和输出 Token 并置 usage_estimated: true，成本字段仍为零。

aisix_usage_events_emitted_total 。描述：用量事件发送尝试，在 AISIX 尝试将事件加入队列前计数，包括被队列接受的事件和被队列拒绝的事件。status 为用量事件记录的状态：在 200 响应头发出后失败的流按该失败的状态计数，例如 502、504 或 499；1.4.0 及更早版本则把大多数此类流计入 200。。类型：counter 。标签数量：10 个标签

`handler` 的值

a2a, audio, batch, batches, chat, completions, count_tokens, embeddings, files, fine_tuning, images, mcp, messages, passthrough_route, realtime, rerank, responses, videos

`status_code` 的值

2xx, 3xx, 4xx, 5xx, other

`inbound_protocol` 的值

openai, anthropic, mcp, other

other 包括 A2A、realtime、passthrough，以及三个具名协议分桶以外的所有其他值。

aisix_usage_event_drops_total 。描述：未能到达控制面的用量事件：既包括交接队列未接受的，也包括 worker 已接受但未能投递的。。类型：counter 。标签数量：7 个标签

`reason` 的值

sink_disabled, sink_full, sink_closed, send_failed, retry_budget_exhausted

sink_disabled、sink_full 和 sink_closed 属于队列侧：事件从未被接受。send_failed（批次未经重发即被放弃——控制面未表明具备去重能力、应答表明该批次永远不可接受，或网关正在关闭）与 retry_budget_exhausted（批次自最早一条事件起已超过 30 分钟，或连续 8 次被应答并拒绝）属于投递侧，按被放弃批次所携带的每条事件各计一次。1.3.0 及更早版本不发射这两个取值。投递侧样本只携带 user_id 和 user_name；model 和两个 Provider Key 标签均为 unknown。

PromQL 示例

sum(rate(aisix_usage_event_drops_total[5m])) by (model, provider_key_name, reason)

aisix_usage_events_rejected_total 。描述：控制面在一个已接受的遥测批次中拒绝的用量事件，按其应答中的 rejected 数量累加。这些事件会被丢弃而不会重发，因为控制面会再次拒绝它们；它们也不计入 aisix_usage_event_drops_total。每个这样的批次还会记录带 batch_id、count 和 rejected 的 control plane rejected usage events in an accepted telemetry batch (events dropped) 日志。仅在托管模式下产生，即网关向控制面上报用量时。1.4.0 及更早版本不产生该指标，这些版本会把任何成功应答都视为全部送达。。类型：counter 。标签数量：无标签

行为

该计数器没有标签，因为控制面只返回一个数量，没有可以归因的具体事件。请在网关日志中按 batch_id 关联。

PromQL 示例

sum(increase(aisix_usage_events_rejected_total[1h]))

aisix_usage_delivery_unhealthy_seconds 。描述：用量事件已等待了多久仍没有任何遥测上报到达控制面，单位为秒。上报正常时为 0。1.7.1 及更早版本不产生该指标。。类型：gauge 。标签数量：无标签

行为

正常运行时，它的读数最多为一个约 5 秒的刷新间隔，因为事件要等待下一个批次。控制面接受该批次或拒绝其内容时，上报即视为到达控制面；连接失败、超时、服务器错误或认证被拒都不会让该 Gauge 归零。

在严格预算执行下，该值达到组织的宽限期后，网关开始以 503 budget_unverified 拒绝受预算约束的流量。参见流量控制部分的「预算」。

不向控制面上报用量的网关上，该值始终为 0。

PromQL 示例

max(aisix_usage_delivery_unhealthy_seconds) > 300

aisix_otlp_fanout_drops_total 。描述：导出器扇出丢失的遥测记录，按导出器和原因统计。尽管指标名里带 OTLP，它覆盖所有可观测性导出器——OTLP/HTTP、阿里云 SLS、对象存储和 Datadog——因为它们都跑在同一条扇出链路上。按记录数而非批次数计数，因此可以与导出器实际投递的数量直接对比：一个失败的批次丢失多少条记录，取决于它携带了多少条。1.1.0 及更早版本不发射该指标。。类型：counter 。标签数量：2 个标签

`reason` 的值

queue_full, worker_stopped, retries_exhausted, permanent_error

queue_full 和 worker_stopped 在入队时被拒绝，每次丢失一条记录。retries_exhausted 和 permanent_error 发生在导出尝试之后，会丢失整个批次。

行为

exporter 是可观测性导出器的配置名称——控制面里的资源，或独立网关资源文件中的对应行。

扇出与用量事件队列是同一发射点上两条互相独立的投递腿，而不是一前一后。两族计数器互不蕴含：同一条记录可能被两者都丢弃、只被其中一条丢弃，或都不丢弃。扇出丢弃不会增加 aisix_usage_event_drops_total。

aisix_otlp_fanout_failures_total 。描述：对某个可观测性导出器的失败导出尝试，每次尝试计数一次，包含重试。与丢弃计数器一样，它覆盖所有导出器类型，不只是 OTLP/HTTP。一个总是到第三次尝试才成功的导出器在这里可见，即使它从未丢失记录——这正是它与 aisix_otlp_fanout_drops_total 的区别。1.1.0 及更早版本不发射该指标。。类型：counter 。标签数量：1 个标签

行为

exporter 是可观测性导出器的配置名称——控制面里的资源，或独立网关资源文件中的对应行。

配置指标

监控 AISIX 是否能从配置源加载并应用变更。

指标条目：14

配置状态

AISIX 在这些指标以及指标和状态监听器的 GET /status/config 中反映相同的实时配置状态。

重新加载指标适用于文件和 etcd 配置源。仅当 AISIX 从 etcd 加载配置时，才会公开修订版本和配置源连接指标。

比较已观测和已应用的修订版本，以判断网关是否正在使用最新的 etcd 配置。

aisix_config_last_reload_successful 。描述：最近一次配置加载是否成功。。类型：gauge 。标签数量：无标签

`指标值` 的值

0, 1

1 表示成功，0 表示失败。

aisix_config_last_reload_success_timestamp_seconds 。描述：最近一次成功加载配置的 Unix 时间戳（秒）。。类型：gauge 。标签数量：无标签

行为

在配置成功加载前不会公开该序列。

aisix_config_reloads_total 。描述：完整配置重新加载尝试，包括配置源获取失败。。类型：counter 。标签数量：无标签

行为

etcd 增量 watch 事件不会增加此计数器。

aisix_config_reload_failures_total 。描述：按原因分组的配置重新加载失败。。类型：counter 。标签数量：1 个标签

`reason` 的值

fetch, parse, validate

fetch 表示无法读取配置源，parse 表示配置源数据无效，validate 表示资源无效。

aisix_config_rejected_resources 。描述：当前被拒绝的资源数，按资源类型分组。。类型：gauge 。标签数量：1 个标签

行为

某类资源的所有拒绝均清除后，AISIX 会将其现有序列设为 0。

aisix_config_partially_compatible_resources 。描述：包含至少一个当前网关版本无法识别字段、但仍在提供服务的资源，按资源类型分组。。类型：gauge 。标签数量：1 个标签

行为

包含多个被忽略字段的资源只计一次。请检查 GET /status/config 中的 partially_compatible，查看字段路径和各字段计数。

某类资源的所有部分兼容资源均清除后，AISIX 会将其现有序列设为 0。

aisix_config_stale_served_resources 。描述：来源中的最新值被拒绝、但最后一个已知良好值仍在提供服务的资源，按资源类型分组。。类型：gauge 。标签数量：1 个标签

行为

请检查 GET /status/config 中的 rejected，确定每项资源及其开始使用陈旧值提供服务的时间。

某类资源不再使用陈旧值提供服务后，AISIX 会将其现有序列设为 0。

aisix_config_unknown_kind_resources 。描述：保留的 etcd 键被归类为 unknown_kind，并按资源类型分组。它们会报告在 GET /status/config 的 unknown_kinds 中，不计入 aisix_config_rejected_resources，也不会把 aisix_config_last_reload_successful 置为 0。1.3.0 及更早版本不发出该指标，这些版本会把此类键计为被拒绝的资源。。类型：gauge 。标签数量：1 个标签

行为

这通常表示控制面投影了一个在该网关之后才发布的资源类型；也可能表示某个已知类型被写入只接受 pricing 的共享定价目录前缀。请检查 unknown_kinds[].last_error 以区分这两种情况。

网关在所有类型中最多保留 256 个未知类型键，与真正被拒绝的资源分开计算。受影响的键超过 256 个时，指标值是下限；发生溢出后，在完整配置重新同步并重建保留集合之前，指标值可能一直不完整。

某类资源不再有保留的未知键后，AISIX 会将其现有序列设为 0。

aisix_config_observed_revision 。描述：网关观测到的最新 etcd 修订版本。。类型：gauge 。标签数量：无标签

`指标值` 的值

0, 1

筛选值 1 可选择当前哈希。应用的配置变更后，AISIX 会保留值为 0 的旧哈希标签。

aisix_config_source_connected 。描述：网关是否已连接到 etcd 配置源。。类型：gauge 。标签数量：无标签

`指标值` 的值

0, 1

1 表示已连接，0 表示未连接。

aisix_config_apply_duration_seconds 。描述：一次配置应用的实际耗时：解析源数据、构建新快照、计算哈希，并将其发布到请求路径。仅在 AISIX 从 etcd 加载配置时发出。1.3.0 及更早版本不发出该指标。。类型：summary 。标签数量：1 个标签

`trigger` 的值

watch, full

watch 表示一批被合并处理的 etcd watch 事件。full 表示读取全部被监听的前缀：一个 watch 周期开始时的加载，以及 watch 中断或修订版本被压缩后的重新同步。

行为

以 summary（摘要）而不是 histogram（直方图）形式公开。它携带的是每个实例在滑动窗口上的分位数，没有 _bucket 序列，因此 histogram_quantile() 对它不会返回任何结果，其分位数也无法跨网关实例聚合。

启动时的第一次应用可能缺失：指标注册表正是在它运行期间建立的。此后的每一次应用都会被记录。

aisix_config_apply_batch_events 。描述：一次配置应用承载了多少变更：trigger="watch" 时为 watch 事件数，trigger="full" 时为读取到的键数量。仅在 AISIX 从 etcd 加载配置时发出。1.3.0 及更早版本不发出该指标。。类型：summary 。标签数量：1 个标签

`trigger` 的值

watch, full

行为

与 aisix_config_apply_duration_seconds 对照阅读，可以区分「控制面写入量很大」和「一次小的写入就要花这么多时间」。

同样以 summary 形式公开，聚合限制与上面的耗时指标相同。

内存指标

找出网关进程的内存由哪一部分占用：内存分配器、异步运行时，以及各个进程内存储。

指标条目：7

解读内存指标

这些序列在 Prometheus 抓取时读取，从不在请求路径上读取，所有标签的取值都是固定集合。1.4.0 及更早版本不发出该指标。

先用 aisix_component_bytes 和 aisix_component_entries 找出正在增长的存储；没有哪个存储能解释增长时，再采集堆 profile。完整的排查流程请参阅可观测性章节中的「内存诊断」。

aisix_allocator_bytes 。描述：内存分配器自身统计的字节数。仅由官方 AISIX 镜像中的 Linux 构建发出。1.4.0 及更早版本不发出该指标。。类型：gauge 。标签数量：1 个标签

`stat` 的值

allocated, active, resident, mapped, retained, metadata

allocated 是存活对象，active 是承载这些对象的页，resident 是位于物理内存中的分配器页，mapped 是分配器映射的页，retained 是已归还操作系统但仍保留地址空间的页，metadata 是分配器自身的簿记开销。

行为

allocated 持续上升说明网关持有的对象变多。resident 远高于 allocated 说明存在碎片，或已释放的页尚未归还操作系统。

aisix_memory_limit_bytes 。描述：进程所受的内存上限，读取自 cgroup v2 的 memory.max 或 cgroup v1 的 memory.limit_in_bytes。进程没有上限时不存在该序列。1.4.0 及更早版本不发出该指标。。类型：gauge 。标签数量：无标签

PromQL 示例

process_resident_memory_bytes / aisix_memory_limit_bytes

aisix_component_entries 。描述：单个进程内存储持有的条目数。1.4.0 及更早版本不发出该指标。。类型：gauge 。标签数量：2 个标签

`component` 的值

usage_event_queue, exporter_queue, log_queue, response_cache, semantic_cache, budget_cache, route_embedding_cache, ratelimit_local_keys, snapshot_pending_reclaim, metric_series, upstream_clients, in_flight_request_bodies

response_cache 和 semantic_cache 统计本进程内持有的条目，不含 Redis 中的条目。ratelimit_local_keys 统计内存限流后端的键，使用 Redis 时为 0。snapshot_pending_reclaim 统计仍被进行中请求持有的已退役配置快照。metric_series 统计网关发布的指标序列数。upstream_clients 统计为带有独立连接设置的服务提供方密钥构建的 HTTP 客户端。in_flight_request_bodies 统计已读取请求体字节的进行中代理请求。budget_cache 统计缓存的预算决策，只有 1.7.1 及更早版本会产生；之后的网关依据配置判定预算，不再有这一缓存。

`exporter` 的值

导出器名称, 空

仅在 component="exporter_queue" 时设置为导出器名称，其他组件为空。导出器删除后，其序列降为 0。

aisix_component_bytes 。描述：单个进程内存储持有的字节数，仅在该存储精确统计字节时发出。1.4.0 及更早版本不发出该指标。。类型：gauge 。标签数量：1 个标签

`component` 的值

log_queue, guardrail_holdback, in_flight_request_bodies

guardrail_holdback 统计为输出安全护栏而保留的流式响应，覆盖 Chat Completions、Messages、Responses（含桥接的 Responses）和透传路由。先整体读取再中继的响应不计入，例如非流式响应和缓冲式音频中继。in_flight_request_bodies 统计进行中代理请求已读取的请求体字节，覆盖所有代理路由。

行为

请求等待上游期间，网关持有约两倍于请求体的内存，因此 in_flight_request_bodies 与 aisix_proxy_in_flight_requests 一同上升，说明大请求正在等待慢上游。

PromQL 示例

aisix_component_bytes{component="in_flight_request_bodies"}

aisix_runtime_alive_tasks 。描述：单个异步运行时上存活的任务数。流量平稳而该值持续增长，说明任务在泄漏。1.4.0 及更早版本不发出该指标。。类型：gauge 。标签数量：1 个标签

`runtime` 的值

control, tpc-0 … tpc-N

control 是承载监听器和后台工作的运行时。tpc-0 到 tpc-N 是每核一线程代理 Worker，仅在启用 proxy.thread_per_core 时存在。

aisix_runtime_global_queue_depth 。描述：在单个异步运行时的共享队列中排队、尚未被 Worker 取走的任务数。runtime 取值与 aisix_runtime_alive_tasks 相同。1.4.0 及更早版本不发出该指标。。类型：gauge 。标签数量：1 个标签

`trigger` 的值

auto, manual

auto 是常驻内存越过阈值时自动写出的 profile，manual 是对 GET /debug/pprof/heap 的请求。

`result` 的值

ok, error

PromQL 示例

increase(aisix_heap_profile_dumps_total{trigger="auto",result="ok"}[1h]) > 0

网关进程指标

监控网关进程本身，与流经它的流量无关。

指标条目：8

aisix_log_lines_dropped_total 。描述：网关因日志接收端消费不及时而丢弃的日志事件。访问日志和应用日志都通过同一个队列写出，因此该计数涵盖两者。1.3.0 及更早版本不发出该指标。。类型：counter 。标签数量：无标签

行为

每次抓取都会发出，因此健康的网关报告 0 而不是没有该序列。这样才能把「没有丢弃」和「该网关版本太旧、无法报告丢弃」区分开。

只要该值上升，就说明那段时间的日志是不完整的：网关继续正常处理了请求，丢掉的是日志行。请排查收集网关标准错误流的组件。

PromQL 示例

increase(aisix_log_lines_dropped_total[5m]) > 0

process_resident_memory_bytes 。描述：网关进程的常驻内存，单位为字节。在 Linux 上以 Prometheus 标准进程采集器的名称发出，现有的进程看板和告警无需修改即可使用。1.4.0 及更早版本不发出该指标。。类型：gauge 。标签数量：无标签

process_virtual_memory_bytes 。描述：网关进程的虚拟内存大小，单位为字节。在 Linux 上以 Prometheus 标准进程采集器的名称发出，现有的进程看板和告警无需修改即可使用。1.4.0 及更早版本不发出该指标。。类型：gauge 。标签数量：无标签

process_cpu_seconds_total 。描述：进程已使用的用户态和内核态 CPU 时间，单位为秒。在 Linux 上以 Prometheus 标准进程采集器的名称发出，现有的进程看板和告警无需修改即可使用。1.4.0 及更早版本不发出该指标。。类型：counter 。标签数量：无标签

process_start_time_seconds 。描述：进程启动时间，自 Unix 纪元起的秒数。在 Linux 上以 Prometheus 标准进程采集器的名称发出，现有的进程看板和告警无需修改即可使用。1.4.0 及更早版本不发出该指标。。类型：gauge 。标签数量：无标签

使用 PromQL 分析指标

配置 Prometheus 表达式浏览器或其他兼容监控界面抓取 AISIX 指标端点后，可使用以下 PromQL 示例。请根据要检查的流量和网关实例调整时间窗口、标签筛选条件和分组维度。

计算成功率

用成功请求速率除以总请求速率可计算成功率。以下查询合并五分钟窗口内的所有模型推理流量：

sum(rate(aisix_llm_requests_total{outcome="success"}[5m]))
  /
sum(rate(aisix_llm_requests_total[5m]))

若要单独分析某个 API，请添加 endpoint 筛选条件或按 endpoint 分组。

若要包括不计为模型推理的流量（MCP 工具调用、A2A Agent 调用、透传路由——endpoint 标签为 /passthrough_route——以及文件、批处理和微调路由），请对 aisix_proxy_requests_total 运行相同查询。该指标包含所有代理请求。

若只测量主路由路径，请将分子和分母限制为未由回退目标处理的请求：

sum(rate(aisix_llm_requests_total{outcome="success", is_fallback="false"}[5m]))
  /
sum(rate(aisix_llm_requests_total{is_fallback="false"}[5m]))

是否将受限流的请求纳入总体取决于运维策略。outcome="rate_limited" 是所有 HTTP 429：网关限流、预算拒绝，以及上游自己返回的 429。若要把它们全部从分母中排除，请使用：

sum(rate(aisix_llm_requests_total{outcome="success"}[5m]))
  /
sum(rate(aisix_llm_requests_total{outcome!="rate_limited"}[5m]))

区分跨协议转换流量

所有详细请求、延迟和 Token 序列都带有两个协议标签：inbound_protocol 表示调用方与 AISIX 通信所使用的协议，upstream_protocol 表示 AISIX 与实际处理该请求的上游通信所使用的协议。同时按两者分组即可得到一张转换矩阵，其中对角线是原生流量，其余单元格都是 AISIX 转换过的流量：

sum by (inbound_protocol, upstream_protocol) (rate(aisix_llm_requests_total[5m]))

协议转换在功能保真度上是有代价的——只存在于协议一侧的特性在另一侧没有对应表达——因此有必要了解有多少流量依赖它。若要单独观察某个方向，同时指定两端即可：

# Anthropic 协议调用方，由 OpenAI 形态的上游提供服务
sum(rate(aisix_llm_requests_total{inbound_protocol="anthropic", upstream_protocol="openai"}[5m]))

比较不同上游协议的可靠性，可以区分服务商问题和协议转换问题。若调用方相同而某个协议的成功率明显偏离，说明差异出在上游一侧：

sum by (upstream_protocol) (rate(aisix_llm_requests_total{outcome="success"}[5m]))
  /
sum by (upstream_protocol) (rate(aisix_llm_requests_total[5m]))

当请求完全没有选中上游时，upstream_protocol 报告 unknown——例如模型不存在、被输入安全护栏拦截、被控制面预算拒绝，或请求体在转发前被拒绝。这些都是真实的失败，因此在计算成功率时应保留在分母中；只有在专门比较各上游时才应排除它们。

请勿改用 provider 推导上游协议。provider 是开放的厂商字符串，同一厂商可以通过多个适配器接入，而通过 OpenAI 兼容端点接入的自定义厂商使用的是运维人员自行填写的名称。在 PromQL 中手工维护厂商到协议的映射，恰恰会对该标签所要描述的这部分流量给出错误结果。

计算聚合延迟百分位数

计算百分位数前，请跨网关实例合并直方图分桶。P90 表示 90% 的观测值小于或等于该值。请在 sum by 分组中保留 le；需要细分时，可添加 model 或 provider 等标签：

# 所有匹配网关实例的 P90 端到端延迟
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_e2e_latency_seconds_bucket{side!="upstream", status_class="2xx"}[5m]))
)

# 各模型的 P90 端到端延迟
histogram_quantile(
  0.90,
  sum by (le, model) (rate(aisix_request_e2e_latency_seconds_bucket{side!="upstream", status_class="2xx"}[5m]))
)

# 各服务提供方的 P90 首个流式帧延迟
histogram_quantile(
  0.90,
  sum by (le, provider) (rate(aisix_request_ttft_seconds_bucket{side!="downstream"}[5m]))
)

两个 TTFT 指标都带有 side 标签。side="upstream" 测量从服务该请求的那次尝试开始到上游第一个帧的时间；side="downstream" 测量客户端实际等待的时间，即从网关收到请求到写给客户端的第一个帧。不按 side 过滤的 TTFT 查询会混合两者，因此本页示例使用 side!="downstream" 查看上游视角。请优先使用它而不是 side="upstream"：1.4.0 及更早版本的网关不输出 side 标签，在集群升级过程中，side!="downstream" 仍能匹配它们的序列。参见区分网关等待与上游 TTFT。

aisix_request_e2e_latency_seconds 同样带有 side 标签，但本页的端到端示例按相反的方向过滤。side="downstream" 是该直方图一直以来记录的客户端感知延迟；side="upstream" 是产生该响应的那次尝试在上游花费的时间。1.4.0 及更早版本的网关在该直方图上不输出 side 标签，只记录 downstream 数值，因此 side!="upstream" 能在混合版本的集群中选出所有网关的客户端感知延迟。不要照搬 TTFT 的过滤条件：在该直方图上，side!="downstream" 选出的是上游数值。不按 side 过滤的端到端查询会混合两者，上游样本会拉低其百分位数。参见区分网关耗时与上游耗时。

流式端到端时间涵盖完整生成过程，因此流式和非流式请求具有不同的延迟分布。请使用 streaming 标签分别分析：

# 成功流式请求的 P90 端到端延迟
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_e2e_latency_seconds_bucket{side!="upstream", streaming="true", status_class="2xx"}[5m]))
)

比较单实例流式延迟

摘要序列为每个网关实例公开预先计算的 quantile 标签。请选择一个抓取目标以及要检查的模型或服务提供方：

# 流式 chat completions 的 P90 首个流式帧延迟
aisix_llm_time_to_first_token_seconds{endpoint="/v1/chat/completions", side!="downstream", quantile="0.9"}

# 同一批流量的 P90 整个流时长
aisix_llm_request_duration_seconds{endpoint="/v1/chat/completions", stream="true", quantile="0.9"}

两条查询都固定了 endpoint，因为这两个序列默认覆盖的流量并不相同：首个流式帧延迟只对流式响应记录，而持续时间序列覆盖所有模型推理请求，无论是否流式。不加这个过滤条件，其他模型推理端点的流量可能会影响持续时间 P90，却不会计入 TTFT P90。

aisix_llm_request_duration_seconds 在请求结束时记录。对流式请求而言就是流结束时，因此该值覆盖整个生成过程，并以流结束时的状态记录：调用方放弃的流为 499，上游中断或超时的流为 502 或 504。aisix_request_duration_seconds、aisix_proxy_request_duration_seconds 以及对应的请求计数器同样如此。参见响应头发出后失败的流。

在 1.5.0 及更早版本的网关上，这三者都在网关把响应交给客户端时记录。流式请求在这一刻还没有读取任何帧，因此该值只覆盖到响应开始为止的处理，不包含整个生成过程，并且无论流如何结束，请求都计为 200。透传路由此前就已在流结束时记录。

要获取流式请求的端到端延迟，请使用在流结束时记录的 aisix_request_e2e_latency_seconds{side!="upstream"}。它是直方图而非摘要，因此请用上文的分位数查询读取，而不是按实例读取。

对于 A2A 调用，同一直方图使用 endpoint="/a2a"，在 downstream 一侧记录 Agent 调用的完整时长，在 upstream 一侧记录对 Agent 的调用。1.7.1 及更早版本的网关只在 downstream 一侧记录 A2A 调用，并对已进入 A2A 统计、但在下发之前被拒绝的调用记录零时长。对于流式调用，该直方图和 aisix_proxy_request_duration_seconds 都会持续到流结束，被放弃的流在 4xx 状态类中记录为 499。在 1.5.0 及更早版本的网关上，aisix_proxy_request_duration_seconds 在响应开始时就停止计时。

不要对跨实例的摘要分位数取平均值。请使用上述直方图查询计算跨网关实例的百分位数。

区分网关等待与上游 TTFT

比较 aisix_request_ttft_seconds 的两个 side 取值，可以看出客户端等待首个帧的时间中有多少是网关增加的：

# 客户端等待首个帧的 P90 时间
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_ttft_seconds_bucket{side="downstream"}[5m]))
)

# 上游返回首个帧的 P90 时间
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_ttft_seconds_bucket{side!="downstream"}[5m]))
)

downstream 区间涵盖请求解析、输入安全护栏、失败的尝试及其退避等待，以及输出安全护栏的扣留。对于首次尝试即成功的请求，两侧之差是网关侧的工作，通常是安全护栏；对于发生过重试的请求，差值还包含之前的尝试。

downstream 观测是 upstream 观测的子集。在首个帧到达客户端之前被输出安全护栏阻断的流，或在扣留期间被客户端放弃的流，只会记录 upstream 观测。

在两种协议桥接中，客户端收到的第一个帧是第一个携带内容的事件：非 Anthropic 上游的 /v1/messages，以及聊天协议上游的 /v1/responses。这时 downstream 还包含等待该事件的时间，对推理型上游而言就是它的思考时间，因此两侧之差不只是网关的工作。

1.4.0 及更早版本的网关只记录 upstream 区间，且不输出 side 标签，因此 downstream 查询对它们不返回数据。

区分网关耗时与上游耗时

比较 aisix_request_e2e_latency_seconds 的两个 side 取值，可以看出请求的端到端时间中有多少花在上游：

# 客户端感知的 P90 端到端延迟
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_e2e_latency_seconds_bucket{side!="upstream"}[5m]))
)

# 产生响应的那次尝试的 P90 上游耗时
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_e2e_latency_seconds_bucket{side="upstream"}[5m]))
)

upstream 一侧从产生该响应的那次尝试开始计时，直到上游完成：完整收到响应，或者对流式请求而言上游流结束。它与该尝试的用量事件中的 upstream_latency_ms 是同一个数值。每个请求最多记录一次 upstream 观测值，除 side 外，其标签与该请求的 downstream 观测值相同。

只要那次尝试到达了上游，就会记录 upstream 观测值，包括以上游错误或超时结束的尝试。缓存命中、在下发之前失败的请求、合议模型，以及不报告上游尝试的路由（例如 /v1/models、视频状态查询和内容下载请求）只记录 downstream 一侧，因此 upstream 一侧的样本更少；请比较分布而不是计数。更早失败的尝试及其重试退避不会单独观测，只包含在 downstream 数值中，因此对于重试过的请求，两侧之差也包含这些时间。

1.4.0 及更早版本的网关不输出 upstream 一侧，因此 upstream 查询对它们不返回数据。

测量安全护栏延迟和结果

aisix_guardrail_latency_seconds 会为每次计时的安全护栏执行记录一次观测，并使用安全护栏名称、种类、阶段和 result 作为标签。安全护栏通常在每个适用阶段执行一次；流式窗口扫描可以在一条响应中多次执行同一个输出安全护栏。同步的逐字段 PII 和关键词脱敏操作不计入该指标。计算各安全护栏执行延迟的 P95，以验证是否符合审核延迟预算：

histogram_quantile(
  0.95,
  sum by (le, guardrail) (rate(aisix_guardrail_latency_seconds_bucket[5m]))
)

安全护栏顺序执行，因此它们对请求延迟的总贡献等于该请求所有执行时间之和。计算每个安全护栏和阶段的平均执行时间，并与审核延迟预算比较：

sum by (guardrail, phase) (rate(aisix_guardrail_latency_seconds_sum[5m]))
/
sum by (guardrail, phase) (rate(aisix_guardrail_latency_seconds_count[5m]))

要查看安全护栏给客户端等待首个流式帧的时间增加了多少，请比较 TTFT 指标的 side="downstream" 序列与上游序列，参见区分网关等待与上游 TTFT。

使用 kind 标签比较本地检测与远程审核的执行延迟。keyword 和 pii 在进程内运行；semantic 调用配置的向量嵌入模型，custom 的调用位置取决于脚本，其余种类调用审核服务：

histogram_quantile(
  0.95,
  sum by (le, kind) (rate(aisix_guardrail_latency_seconds_bucket[5m]))
)

_count 序列同时也可用作执行计数器。按安全护栏跟踪阻断率和 fail-open 绕过率，并在远程安全护栏开始 fail-open 时发出告警：

sum by (guardrail, result) (rate(aisix_guardrail_latency_seconds_count[5m]))

# 按失败原因统计 fail-open 绕过
sum by (guardrail, error_type) (rate(aisix_guardrail_latency_seconds_count{result="bypassed"}[5m]))

按客户端计算 Token 用量

使用 token_type="total" 按标准化客户端类型计算包含缓存的 Token 用量：

sum by (client_type) (rate(aisix_llm_tokens_by_client_total{token_type="total"}[5m]))

若要比较输入和输出用量，请同时选择两种 Token 类型，并在分组中包含 token_type：

sum by (client_type, token_type) (rate(aisix_llm_tokens_by_client_total{token_type=~"input|output"}[5m]))

按客户端类型和模型细分 Token 用量

model 标签记录客户端请求的模型名称，而不是 AISIX 选择的直接模型。按 client_type 和 model 分组，可以查看各标准化客户端类型如何在不同模型间分配 Token 用量：

sum by (client_type, model) (rate(aisix_llm_tokens_by_client_total{token_type="total"}[5m]))

若要检查单个客户端类型，请按 client_type 筛选，并仅按模型分组：

sum by (model) (rate(aisix_llm_tokens_by_client_total{client_type="claude-code", token_type="total"}[5m]))

计算提示词缓存命中率

上游服务商会缓存提示词前缀，并对命中缓存的输入按远低于标准价格计费，因此「输入中有多少来自缓存」是判断提示词缓存是否划算的唯一关键数字。AISIX 用三个计数器报告它，而它们之间的拆分正是让查询在不同服务商之间都成立的原因：

计数器	上游的上报方式	与 `aisix_llm_input_tokens_total` 的关系
`aisix_llm_cached_input_tokens_total`	计入提示词 Token 数量之内	已包含在其中
`aisix_llm_cache_read_input_tokens_total`	与输入 Token 并列的独立计数	在其之外
`aisix_llm_cache_creation_input_tokens_total`	与输入 Token 并列的独立计数	在其之外

因此请求实际消耗的输入是 input + cache_read + cache_creation，其中来自缓存的部分是 cached + cache_read。无论服务商采用哪种口径，这两个表达式都成立，因此该命中率在混合部署中也可以横向比较：

(
  sum(rate(aisix_llm_cached_input_tokens_total[5m]))
  + sum(rate(aisix_llm_cache_read_input_tokens_total[5m]))
)
  /
(
  sum(rate(aisix_llm_input_tokens_total[5m]))
  + sum(rate(aisix_llm_cache_read_input_tokens_total[5m]))
  + sum(rate(aisix_llm_cache_creation_input_tokens_total[5m]))
)

给每个 sum 都加上 by (model)，即可看出哪些工作负载真正受益。前缀稳定的提示词——较长的系统提示词、固定的工具结构、固定的文档——命中率应当稳定在较高水平；每次调用都改写开头的提示词则会一直接近零，是应当优先重构的对象。

缓存写入的单价高于普通输入 Token，缓存读取则低得多，因此写入远多于读取的工作负载是在为一个没人命中的缓存付溢价。对同时上报两者的服务商，可监控该比值：

sum by (model) (rate(aisix_llm_cache_creation_input_tokens_total{upstream_protocol=~"anthropic|bedrock"}[5m]))
  /
sum by (model) (rate(aisix_llm_cache_read_input_tokens_total{upstream_protocol=~"anthropic|bedrock"}[5m]))

若该比值在较长窗口内持续明显大于 1，说明缓存条目在被复用之前就已过期。可缩短共享同一前缀的调用之间的间隔，或者干脆不再缓存该提示词。

每个计数器只在取值非零后才创建，因此不报告缓存明细的服务商不会产生任何序列，此时对其求 sum() 得到的是空结果而不是 0。若告警需要在出现缓存流量之前就能求值，请用 or vector(0) 包裹查询。

这三个计数器描述的是上游服务商的提示词缓存。AISIX 响应缓存是另一套机制，由 aisix_cache_requests_total 度量，参见测量响应缓存效果。

计算单请求 Token 数

sum by (endpoint, model) (rate(aisix_llm_total_tokens_total[5m]))
  /
sum by (endpoint, model) (rate(aisix_llm_requests_total[5m]))

分组中必须保留 endpoint。/v1/audio/speech 按输入字符计费，/v1/videos 按视频计费，两者都计为请求但不报告 Token；跨端点求和会按这部分流量的占比拉低平均值。

aisix_llm_total_tokens_total 是包含缓存的：它包含输入、输出，以及服务商与输入并列上报的缓存读取和缓存写入 Token。这使它成为单请求消耗量的正确分子，同时也是缓存命中率的错误分子——后者请使用计算提示词缓存命中率中的查询。

排查用量最高的调用方

Token 计数器带有完整的调用方身份标签，因此用 topk 就能定位用量最高的调用方：

# Token 速率最高的十个 API Key
topk(10, sum by (api_key_id) (rate(aisix_llm_total_tokens_total[1h])))

# Token 速率最高的十个用户
topk(10, sum by (user_id, user_name) (rate(aisix_llm_total_tokens_total[1h])))

# 某个团队的 Token 用量分布在哪些模型上
sum by (model) (rate(aisix_llm_total_tokens_total{team_id="team-platform"}[1h]))

网关不导出支出指标。支出以控制面为每个请求记录的费用为准，每个用量事件仍携带 cost_usd。1.7.1 及更早版本的网关还会导出 aisix_llm_spend_micro_usd_total，它只记录网关为 Realtime 会话自行估算的支出。

user_name 和 provider_key_name 与各自的 ID 一一对应，因此在分组中加入名称不会增加序列数量。在控制面提供之前，user_name 报告 unknown。如需按 API 密钥或团队的显示名称分组，可在该指标族的标签中添加 api_key_name 或 team_name，参见名称标签。

测量响应缓存效果

aisix_cache_requests_total 统计的是命中了某个已启用、且后端可用的缓存策略的请求。没有匹配策略的请求完全不计入，因此该指标衡量的是已配置策略的效果，而不是全部流量中被缓存的比例：

sum by (policy) (rate(aisix_cache_requests_total{outcome=~"hit_exact|hit_semantic"}[5m]))
  /
sum by (policy) (rate(aisix_cache_requests_total[5m]))

按 outcome 拆分即可看出语义层相对精确匹配的额外收益，这也是它所付出的向量嵌入调用是否值得的依据：

sum by (policy, outcome) (rate(aisix_cache_requests_total[5m]))

语义层失败会退化为普通未命中，因此向量嵌入模型或存储故障与「命中率本来就低」在结果计数器中完全一样。对失败计数器告警才能区分两者：

sum by (policy, cause) (rate(aisix_cache_semantic_embedding_failures_total[5m])) > 0
sum by (policy, op) (rate(aisix_cache_semantic_store_failures_total[5m])) > 0

该缓存与上游服务商的提示词缓存相互独立，但两者存在一个值得注意的单向影响：命中 AISIX 响应缓存的请求根本不会到达上游，因此不会为服务商缓存计数器贡献任何数据。响应缓存命中率上升会拉低提示词缓存的绝对 Token 速率，但这并不意味着提示词缓存的效果变差了。

测量目标健康度与故障转移

请求指标说明调用方经历了什么，部署指标说明是哪个目标造成的。一个成功率看起来很健康的模型组，可能正掩盖着某个持续失败、只是被故障转移一直救回来的目标。把两者放在一起看：

# 每个被尝试目标的失败率
sum by (model, upstream_model, provider_key_id) (rate(aisix_deployment_failure_responses_total[5m]))
  /
sum by (model, upstream_model, provider_key_id) (rate(aisix_deployment_requests_total[5m]))

# 由故障转移目标提供服务的客户端请求占比
sum(rate(aisix_llm_requests_total{is_fallback="true"}[5m]))
  /
sum(rate(aisix_llm_requests_total[5m]))

故障转移占比上升而成功率保持平稳，正是需要采取行动的信号：调用方仍然得到了服务，而主目标正在其背后劣化。

# 当前已被移出轮转的目标数
count by (model) (aisix_deployment_state == 2)

# 目标进入冷却的频率
sum by (model, upstream_model) (rate(aisix_deployment_cooled_down_total[15m]))

部署计数器按每次上游尝试采样，因此一个跨三个目标故障转移的客户端请求在这里是三个样本，在请求指标中只有一个样本。不要用一个指标族去除以另一个。

监控限流并诊断预算拒绝

以下限流指标适用于所有 AISIX 网关。预算 Gauge 指标描述预算拒绝，并不会持续提供当前支出数据。

以 HTTP 429 应答的请求占比来自请求指标族的 outcome 标签，它覆盖所有端点。rate_limited 是所有 429，因此除网关限流外，该占比还包括预算拒绝和上游自己返回的 429：

sum(rate(aisix_llm_requests_total{outcome="rate_limited"}[5m]))
  /
sum(rate(aisix_llm_requests_total[5m]))

若要只统计网关自身的限流拒绝，并区分请求数限流和 Token 限流，请使用专用计数器的 scope 标签：

sum by (scope) (rate(aisix_ratelimit_rejections_total[5m]))

当网关因阻断型预算超限而拒绝请求时，预算 Gauge 指标会记录拒绝详情。它们使用相同的 api_key_id、team_id、user_id 和 user_name 标签，因此可以比较上报的支出与限额：

# 上报的支出相对于阻断请求的限额的比例
(aisix_budget_spent_usd / aisix_budget_limit_usd)
  and on (api_key_id, team_id, user_id) (aisix_budget_details_present == 1)

请务必加上 aisix_budget_details_present == 1 这一条件。后续请求未被预算拒绝时，不会把其他 Gauge 指标置零，它们仍保留上次拒绝时的金额，因此未加保护的比值可能显示陈旧数据。这个标志位用于区分两者。

这些 Gauge 指标无法在网关阻断请求前发出预警，因为它们的值来自拒绝响应。请配置预算告警与通知，在阻断型预算开始拒绝流量前接收阈值通知。

当一把 Key 消失之后

aisix_budget_* 和 aisix_ratelimit_remaining_* 只在处理请求的过程中写入，而 Prometheus 序列一旦产生就不会被删除。因此 AISIX 会主动让它们退休：API Key 被删除之后的数秒内，陈旧的样本会被改写为 NaN，aisix_budget_details_present 则写为 0。API Key 被改绑到其他团队或成员、或其成员名称变化时，预算 Gauge 也会退休，因为这会开出一条新序列并让旧的搁浅。剩余配额 Gauge 不携带团队或成员标签；它们报告的模型不再存在时也会退休。选择了 api_key_name 或 team_name 时，对应名称变化也会让旧序列退休。

用 NaN 而不是 0 是有意的。aisix_ratelimit_remaining_requests 0 的含义是调用方配额已耗尽，aisix_budget_remaining_usd 0 的含义是预算已花完，所以把退休序列置零等于把一个陈旧的读数换成一个错误的读数。NaN 与阈值进行 >、<、>= 或 <= 比较时，结果都为假，因此使用这些比较运算符的告警不会继续被退休序列触发。有两点需要预先考虑：

序列本身仍然存在，因此 absent() 不会把它报告为缺失。
对含有退休序列的指标族做聚合，结果也是 NaN——sum(aisix_budget_spent_usd) 返回 NaN 而不是当前总额。请按某个身份标签分组，或先用 aisix_budget_details_present == 1 过滤。上面那几条逐序列的查询不受影响。

aisix_deployment_state 不会退休。它只在部署的健康状态发生变化时才写入，所以清空它会让一个活着的模型在下次状态跳变之前完全没有状态可报。因此，一个在冷却期间被删除的模型，会一直被 count by (model) (aisix_deployment_state == 2) 计入，直到网关重启。

测量并发与被放弃的请求

aisix_proxy_in_flight_requests 是代理上的实时并发量，网关容量应按它来规划，而不是按请求速率：

sum by (endpoint, inbound_protocol) (aisix_proxy_in_flight_requests)

在响应头发出之前就断开连接的调用方不会产生正常的请求结果，因此不会出现在请求计数器中；要计算放弃率，必须把它们重新加回分母：

sum(rate(aisix_proxy_client_cancelled_requests_total[5m]))
  /
(
  sum(rate(aisix_proxy_requests_total[5m]))
  + sum(rate(aisix_proxy_client_cancelled_requests_total[5m]))
)

放弃通常意味着调用方在等待首个 Token 时失去了耐心。按 model 细分，并与同一模型的首 Token 时间对比：

sum by (model) (rate(aisix_proxy_client_cancelled_requests_total[5m]))

认证被拒是另一种静默故障模式——密钥轮换或签发方配置错误，往往在有人报障之前很久就会在这里显现：

sum by (method, reason) (rate(aisix_auth_decisions_total{result="denied"}[5m]))

验证用量事件投递

用量事件是计费和分析的数据来源，因此应单独对事件静默丢失的情况设置告警。每次发送尝试要么被投递队列接受，要么被计为丢弃：

sum(rate(aisix_usage_event_drops_total[5m]))
  /
sum(rate(aisix_usage_events_emitted_total[5m]))

两个计数器都带有 model、provider_key_id 和 provider_key_name，因此同样的除法在每个模型、每个 Provider Key 维度上也成立。丢弃率集中在其中某一项，就指明了哪部分流量的用量记录丢失了：

sum by (model, provider_key_name, reason) (rate(aisix_usage_event_drops_total[5m]))

队列接受不等于成功写入存储。工作线程接受事件之后，控制面上报仍可能失败：被工作线程放弃的批次会把其中每条事件计入 reason="send_failed" 或 reason="retry_budget_exhausted"，这些样本只携带成员标签，model 和 Provider Key 标签为 unknown。导出器管道是另一条独立链路，从不增加该计数器，其丢失由 aisix_otlp_fanout_drops_total 统计。

控制面也可能接受一个批次，却拒绝其中的个别事件。这些事件会被丢弃而不会重发，并由 aisix_usage_events_rejected_total 统计，而不是计入丢弃计数器。只要它有增长，就说明用量日志中缺少记录：

sum(increase(aisix_usage_events_rejected_total[1h])) > 0

对配置问题告警

无法加载配置的网关会继续使用上一份可用配置提供服务，因此其表现是「毫无反应」而不是报错。请直接对状态告警：

# 最近一次加载失败
aisix_config_last_reload_successful == 0

# 已连续五分钟没有成功加载
time() - aisix_config_last_reload_success_timestamp_seconds > 300

# 网关拒绝的资源，按类型分组
sum by (kind) (aisix_config_rejected_resources) > 0

# 正在提供服务的 etcd 修订版本落后于已观测到的修订版本
aisix_config_observed_revision - aisix_config_applied_revision > 0

aisix_config_partially_compatible_resources 统计携带当前网关版本无法识别字段的资源。在先升级控制面的流程中，较旧网关接收到来自较新控制面的字段时，该指标可能上升。网关升级完成后，它应当归零：

sum by (kind) (aisix_config_partially_compatible_resources) > 0

以上任一情况的具体资源和字段路径，可在指标监听器的 GET /status/config 中查看。

aisix_config_apply_duration_seconds 和 aisix_config_apply_batch_events 按 trigger 分别报告每次应用的耗时以及它承载的变更量。当配置写入看起来影响到请求延迟时，应把两者对照阅读：批次大小稳定而耗时上升，说明问题出在配置规模；批次大小上升，则说明控制面写入变多了。

对丢弃的日志行告警

网关通过一个有界队列写出日志，因此停止消费的日志采集端损失的是日志行，而不是请求延迟。该值只要上升，就说明那段时间的日志不完整：

increase(aisix_log_lines_dropped_total[5m]) > 0

该序列在每次抓取时都会发出，因此健康的网关报告 0 而不是没有该序列。请参阅消化消费缓慢的日志接收端。

配置指标

在启动时配置自定义客户端分类和直方图分桶边界。变更会在网关重启后生效，并可能改变标签值或分桶序列，因此应同时协调仪表盘、告警和记录规则。

将自定义客户端映射到客户端类型

AISIX 开箱即用地识别常见 AI 编程客户端和 SDK。若要对内部工具进行分类，或将被内置规则归入 node 等通用类别的客户端重新分类，请在网关配置中定义映射规则：

config.yaml
observability:
  metrics:
    client_type_rules:
      - pattern: "^billing-batcher/"
        client: billing-batcher
      - pattern: "internal-eval-harness"
        client: eval-harness

每条规则将正则表达式映射到固定的 client 值，AISIX 将其作为 client_type 标签公开。规则会在内置规则之前按顺序与原始 User-Agent 请求头匹配，首个匹配项生效。匹配不区分大小写且默认不锚定；需要前缀匹配时，请使用 ^ 锚定模式。

标签使用 client 值，而不是请求的 User-Agent，因此无论客户端发送什么内容，标签集合都保持有界。配置限制进一步保证这一点：最多 64 条规则，模式最长 512 字节，client 值最长 64 个字符且必须匹配 [a-z0-9][a-z0-9._-]*。AISIX 会在启动时验证规则，遇到无效规则时拒绝启动；变更在重启后生效。

User-Agent 为空的请求始终报告为 unknown；未匹配任何规则的请求会继续使用内置分类。

自定义直方图分桶

以下四个指标是带有 le 分桶边界的 Prometheus 直方图。由于各自分布不同，每个指标都有自己的默认边界：

指标	默认边界（秒）
`aisix_request_e2e_latency_seconds`	0.005、0.01、0.025、0.05、0.1、0.25、0.5、1、2、5、10、30、60、120、300、420、600
`aisix_request_ttft_seconds`	0.05、0.1、0.25、0.5、1、2、5、10、30、60、120、300
`aisix_guardrail_latency_seconds`	0.001、0.0025、0.005、0.01、0.025、0.05、0.1、0.25、0.5、1、2.5、5、10、30
`aisix_a2a_ttfb_seconds`	0.05、0.1、0.25、0.5、1、2、5、10、30、60、120、300

端到端延迟包括缓存命中和分发前被拒绝的请求，因此需要毫秒级边界。首个 Token 时间（TTFT）在上游流式输出的首个帧到达时记录，无论帧内容为何；使用托管服务提供方时，低于 50 毫秒的分桶通常为空。安全护栏指标既需要覆盖快速的进程内检查，也需要覆盖远程审核服务，因此同时使用较低和较高的边界。A2A Agent 发出首个流式事件的耗时默认沿用 TTFT 的边界，但使用独立的 a2a_ttfb 覆盖项，因为 Agent 任务可能思考几分钟才开口。

如果流量具有不同的分布，可以分别覆盖每个指标的边界。例如，与网关位于同一节点的 vLLM 或 Ollama 模型服务器可能在几毫秒内生成首个输出：

config.yaml
observability:
  metrics:
    buckets:
      request_ttft: [0.005, 0.01, 0.025, 0.05, 0.1, 0.5, 1, 5, 30]

每个字段均为可选，并且只替换其对应指标的边界；未指定的指标保留默认值。提供的列表必须包含 1–64 个有限、正数且严格递增的边界。不要列出 +Inf，AISIX 会自行添加该分桶。AISIX 会在启动时验证配置，遇到无效列表时拒绝启动；变更会在重启后生效。

每个边界都会为每组标签组合增加一个 _bucket 时间序列，因此列表越长，采集器需要存储的序列就越多。

对于使用 AISIX Helm Chart 部署的网关，请在 config.observability.metrics.buckets 下设置该列表：

config:
  observability:
    metrics:
      buckets:
        request_ttft: [0.005, 0.01, 0.025, 0.05, 0.1, 0.5, 1, 5, 30]

警告

修改边界会改变输出的 _bucket 序列。选择已移除 le 值的仪表盘或记录规则将不再匹配。不要比较变更前后由分桶计算的分位数。

有关 Helm 配置模式，请参阅设置其他网关配置。

指标目录

指标类型

请求指标

标签

outcome 的值

行为

PromQL 示例

标签

inbound_protocol 的值

upstream_protocol 的值

stream 的值

is_fallback 的值

outcome 的值

行为

标签

inbound_protocol 的值

upstream_protocol 的值

stream 的值

is_fallback 的值

outcome 的值

行为

标签

inbound_protocol 的值

upstream_protocol 的值

stream 的值

is_fallback 的值

outcome 的值

标签

inbound_protocol 的值

行为

PromQL 示例

标签

行为

PromQL 示例

标签

inbound_protocol 的值

outcome 的值

行为

PromQL 示例

标签

method 的值

result 的值

行为

PromQL 示例

延迟指标

标签

行为

标签

inbound_protocol 的值

upstream_protocol 的值

stream 的值

outcome 的值

标签

inbound_protocol 的值

upstream_protocol 的值

stream 的值

outcome 的值

标签

side 的值

inbound_protocol 的值

upstream_protocol 的值

行为

标签

side 的值

status_class 的值

streaming 的值

行为

PromQL 示例

标签

side 的值

status_class 的值

streaming 的值

行为

PromQL 示例

用量与成本指标

标签

标签

inbound_protocol 的值

upstream_protocol 的值

标签

`outcome` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`stream` 的值

`is_fallback` 的值

`outcome` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`stream` 的值

`is_fallback` 的值

`outcome` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`stream` 的值

`is_fallback` 的值

`outcome` 的值

`inbound_protocol` 的值

`inbound_protocol` 的值

`outcome` 的值

`method` 的值

`result` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`stream` 的值

`outcome` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`stream` 的值

`outcome` 的值

`side` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`side` 的值

`status_class` 的值

`streaming` 的值

`side` 的值

`status_class` 的值

`streaming` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`endpoint` 的值

`inbound_protocol` 的值

`upstream_protocol` 的值

`client_type` 的值

`token_type` 的值

`scope` 的值

`layer` 的值

`指标值` 的值

`outcome` 的值

`cause` 的值

`op` 的值

`operation` 的值