跳到主要内容
版本：1.4.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 首次记录相应活动时注册，因此流量指标可能不会在启动后立即出现。请通过代理发送请求，然后再次抓取，即可看到相应序列。

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

指标目录

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

指标
70
系列
11
查询行为

指标类型

counter

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

gauge

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

histogram

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

summary

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

系列
类型
共 70 个条目，当前显示 70 个

请求指标

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

指标条目：8
详细请求标签

本族的每个计数器都是每次客户端请求采样一次，其 status 是调用方实际收到的状态码。第一个目标失败、随后由回退目标成功处理的请求，在这里只是一个 status="200" 样本；它所恢复的那次失败在本族中完全没有体现。统计上游尝试请使用部署指标，查看单次尝试请使用用量日志。

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

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

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

inbound_protocol 是由标准化端点推导出的有界协议类型集合。Anthropic 协议端点报告 anthropic；/mcp、/a2a、/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 是开放的厂商字符串，同一厂商可以通过不同的 adapter 接入，因此从厂商名到协议的 PromQL 映射需要手工维护，并且会对所有自定义厂商和 OpenAI 兼容厂商给出错误结果。

endpoint 始终是标准化的路由模板，而不是原始请求路径。带路径参数的路由会合并为一条序列，例如 /v1/batches/:id、/v1/videos/:id 和 /mcp/{server}；/passthrough/ 下的路径使用 /passthrough_route，无法识别的路径报告为 other。

aisix_requests_total 。描述：兼容性序列中的代理请求结果，覆盖的端点范围最广。 。类型：counter 。标签数量：4 个标签
标签
provider, model, status, outcome
outcome 的值
success, client_error, rate_limited, upstream_error

success 表示 HTTP 200–399；client_error 表示除 429 外的 HTTP 400–499；rate_limited 表示 HTTP 429；其他所有状态均映射为 upstream_error。

行为

A2A 智能体调用使用 provider="a2a" 和 model="a2a"。

PromQL 示例
sum(rate(aisix_requests_total[5m])) by (outcome)
aisix_llm_requests_total 。描述：模型推理请求的结果，包括成功和失败的请求。 。类型：counter 。标签数量：16 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name, stream, is_fallback, status, outcome
inbound_protocol 的值
openai, anthropic, realtime
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

success 表示 HTTP 200–399；client_error 表示除 429 外的 HTTP 400–499；rate_limited 表示 HTTP 429；其他所有状态均映射为 upstream_error。

行为

覆盖调用模型的端点：聊天补全、补全、消息、Token 计数、响应、向量嵌入、重排序、音频、图像生成、视频和 realtime 会话。未调用模型的请求只计入 aisix_proxy_requests_total，包括 MCP 工具调用、A2A Agent 调用、服务提供方透传，以及文件、批处理和微调管理路由。

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

aisix_proxy_requests_total 。描述：所有代理流量（包括模型推理和其他流量）的详细请求结果。 。类型：counter 。标签数量：16 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name, stream, is_fallback, status, outcome
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

success 表示 HTTP 200–399；client_error 表示除 429 外的 HTTP 400–499；rate_limited 表示 HTTP 429；其他所有状态均映射为 upstream_error。

行为

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

aisix_proxy_failed_requests_total 。描述：结果不为 success 的代理请求子集。 。类型：counter 。标签数量：16 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name, stream, is_fallback, status, outcome
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；其他所有状态均映射为 upstream_error。

aisix_proxy_in_flight_requests 。描述：代理当前正在处理的请求，按标准化端点和入站协议分组。 。类型：gauge 。标签数量：2 个标签
标签
endpoint, inbound_protocol
inbound_protocol 的值
openai, anthropic, mcp, a2a, realtime, passthrough
行为

MCP 请求使用 inbound_protocol="mcp"；聚合网关使用 endpoint="/mcp"，按服务器划分的端点使用 endpoint="/mcp/{server}"。A2A 调用使用 endpoint="/a2a" 和 inbound_protocol="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 个标签
标签
endpoint, model, provider_key_id, provider_key_name
行为

这些请求不会产生正常结果，因此不会出现在其他请求计数器中。网关会在此处记录它们，并在访问日志中以状态码 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 个标签
标签
endpoint, inbound_protocol, outcome
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, result, reason
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 标识连接到 AISIX Cloud 的 AISIX 网关所服务的环境；AISIX 网关未连接 AISIX Cloud 时其值为 unknown。status_class 为 2xx、3xx、4xx、5xx 或 other。为控制分桶序列数量，不包含按密钥和按用户的标签；这些维度请使用用量分析。

aisix_request_duration_seconds 。描述：兼容性序列中各代理端点的请求持续时间。HTTP 流式请求记录到响应开始的时间；realtime 记录 WebSocket 会话关闭前的完整持续时间。 。类型：summary 。标签数量：3 个标签
标签
provider, model, status
行为

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

aisix_llm_request_duration_seconds 。描述：模型推理端点的详细请求持续时间。HTTP 流式请求记录到响应开始的时间；realtime 记录 WebSocket 会话关闭前的完整持续时间。 。类型：summary 。标签数量：15 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name, stream, status, outcome
inbound_protocol 的值
openai, anthropic, realtime
upstream_protocol 的值
openai, anthropic, bedrock, vertex, azure-openai, unknown

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

stream 的值
false, true
outcome 的值
success, client_error, rate_limited, upstream_error

success 表示 HTTP 200–399；client_error 表示除 429 外的 HTTP 400–499；rate_limited 表示 HTTP 429；其他所有状态均映射为 upstream_error。

aisix_proxy_request_duration_seconds 。描述：所有代理流量的详细请求持续时间。HTTP 流式请求记录到响应开始的时间；realtime 记录 WebSocket 会话关闭前的完整持续时间。 。类型：summary 。标签数量：15 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name, stream, status, outcome
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

success 表示 HTTP 200–399；client_error 表示除 429 外的 HTTP 400–499；rate_limited 表示 HTTP 429；其他所有状态均映射为 upstream_error。

aisix_llm_time_to_first_token_seconds 。描述：流式聊天补全、消息和响应请求中，到首个流式帧的时间。side 标签（1.4.0 及更早版本不发射）区分上游区间与客户端实际等待的区间。 。类型：summary 。标签数量：13 个标签
标签
side, endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name
side 的值
upstream, downstream

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

inbound_protocol 的值
openai, anthropic
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 区间还包含等待该事件的时间，对推理型上游而言就是它的思考时间。

aisix_request_e2e_latency_seconds 。描述：客户端感知的聊天补全、消息和响应延迟，以及 A2A 的 Agent 调用延迟，包括完整的流式传输时长。 。类型：histogram 。标签数量：6 个标签
标签
env_id, endpoint, model, provider, status_class, streaming
status_class 的值
2xx, 3xx, 4xx, 5xx, other
streaming 的值
false, true
行为

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

每个纳入该指标的模型推理请求只观测一次。非流式请求和失败请求在处理程序返回时记录。流式请求在流结束时记录，包括客户端取消的情况；取消的模型流保留已提交的状态，并记录截至取消时的时长。

A2A 调用使用 endpoint="/a2a"。已下发的调用记录 Agent 调用的完整时长，包含完整的流。已进入 A2A 统计、但在下发之前被拒绝的调用记录为零时长，被放弃的 A2A 流在 4xx 状态类中记录为 499。在进入 A2A 统计之前就被拒绝的调用不会出现在该直方图中。

PromQL 示例
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_e2e_latency_seconds_bucket[5m]))
)
aisix_request_ttft_seconds 。描述：流式聊天补全、消息和响应请求中，到首个流式帧的时间。side 标签（1.4.0 及更早版本不发射）区分上游区间与客户端实际等待的区间。 。类型：histogram 。标签数量：7 个标签
标签
side, env_id, endpoint, model, provider, status_class, streaming
side 的值
upstream, downstream

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

status_class 的值
2xx, 3xx, 4xx, 5xx, other
streaming 的值
true
行为

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

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

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

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

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

默认分桶范围为 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 数量的端点都会在此记录，包括聊天补全、补全、消息、响应、向量嵌入、重排序、音频转录路由、图像生成和 realtime 会话。

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

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

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

各服务商对缓存读取采用两种不同的计量口径，因此读取侧有两个计数器而非一个。aisix_llm_cached_input_tokens_total 对应 OpenAI 口径：缓存命中的 Token 本身就属于上报的 prompt 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。这两个表达式对任一服务商口径都成立。参见计算 Prompt Cache 命中率。

aisix_tokens_consumed_total 。描述：所有报告 Token 用量的端点的 Token 总数，属于覆盖范围最广的兼容性序列。 。类型：counter 。标签数量：2 个标签
标签
provider, model
aisix_llm_input_tokens_total 。描述：上游在所有报告 Token 用量的端点中报告的输入 Token 数。 。类型：counter 。标签数量：12 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name
inbound_protocol 的值
openai, anthropic, realtime
upstream_protocol 的值
openai, anthropic, bedrock, vertex, azure-openai, unknown

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

aisix_llm_output_tokens_total 。描述：上游在所有报告 Token 用量的端点中报告的输出 Token 数。 。类型：counter 。标签数量：12 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name
inbound_protocol 的值
openai, anthropic, realtime
upstream_protocol 的值
openai, anthropic, bedrock, vertex, azure-openai, unknown

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

aisix_llm_total_tokens_total 。描述：上游在所有报告 Token 用量的端点中报告的 Token 总数。 。类型：counter 。标签数量：12 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name
inbound_protocol 的值
openai, anthropic, realtime
upstream_protocol 的值
openai, anthropic, bedrock, vertex, azure-openai, unknown

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

aisix_llm_cached_input_tokens_total 。描述：上游用其 Prompt Cache 提供、并计入 prompt Token 数量的输入 Token。 。类型：counter 。标签数量：12 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name
inbound_protocol 的值
openai, anthropic, realtime
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 。描述：上游用其 Prompt Cache 提供、并与输入 Token 数量分开上报的输入 Token。 。类型：counter 。标签数量：12 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name
inbound_protocol 的值
openai, anthropic, realtime
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 。描述：写入上游 Prompt Cache 的输入 Token。 。类型：counter 。标签数量：12 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name
inbound_protocol 的值
openai, anthropic, realtime
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 美元等于 1,000,000 微美元。网关只要能够解析请求价格，就会记录该指标。 。类型：counter 。标签数量：12 个标签
标签
endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name
inbound_protocol 的值
openai, anthropic, realtime
upstream_protocol 的值
openai, anthropic, bedrock, vertex, azure-openai, unknown

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

aisix_llm_tokens_by_client_total 。描述：所有报告 Token 用量的端点中的 Token 用量，按标准化客户端、请求模型和 Token 类型分组。 。类型：counter 。标签数量：3 个标签
标签
client_type, model, token_type
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, layer, policy_id
scope 的值
requests, tokens

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

layer 的值
api_key, model, mcp, policy
行为

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

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

aisix_ratelimit_remaining_requests 。描述：处理聊天补全请求时报告的剩余请求配额，按 API Key 和模型分组。 。类型：gauge 。标签数量：2 个标签
标签
api_key_id, model
行为

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

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

aisix_ratelimit_remaining_tokens 。描述：处理聊天补全请求时报告的剩余 Token 配额，按 API Key 和模型分组。 。类型：gauge 。标签数量：2 个标签
标签
api_key_id, model
行为

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

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

aisix_budget_limit_usd 。描述：预算上限（美元）。 。类型：gauge 。标签数量：4 个标签
标签
api_key_id, team_id, user_id, user_name
行为

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

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

aisix_budget_spent_usd 。描述：已用预算（美元）。 。类型：gauge 。标签数量：4 个标签
标签
api_key_id, team_id, user_id, user_name
行为

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

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

aisix_budget_remaining_usd 。描述：剩余预算（美元）。 。类型：gauge 。标签数量：4 个标签
标签
api_key_id, team_id, user_id, user_name
行为

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

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

aisix_budget_reset_seconds 。描述：距离预算周期重置的秒数。 。类型：gauge 。标签数量：4 个标签
标签
api_key_id, team_id, user_id, user_name
行为

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

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

aisix_budget_details_present 。描述：是否已填充预算详情。 。类型：gauge 。标签数量：4 个标签
标签
api_key_id, team_id, user_id, user_name
指标值 的值
0, 1

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

缓存指标

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

指标条目：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 拆分可以看出语义层在精确匹配之上贡献了多少。

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

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

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

aisix_cache_semantic_embedding_seconds 。描述：语义层 embedding 调用的延迟，按策略统计。无固定桶的摘要系列。 。类型：summary 。标签数量：1 个标签
标签
policy
aisix_cache_semantic_embedding_failures_total 。描述：语义层的 embedding 失败。失败的请求不经缓存直接发往上游。 。类型：counter 。标签数量：2 个标签
标签
policy, cause
cause 的值
resolve, embed

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

aisix_cache_semantic_store_failures_total 。描述：语义存储的操作失败，按操作统计。进程内存储不会失败；共享（Redis）存储可能失败。失败退化为普通未命中。 。类型：counter 。标签数量：2 个标签
标签
policy, op
op 的值
lookup, store
aisix_redis_failures_total 。描述：对 Redis 后端存储的失败操作，每次操作失败计数一次。它覆盖所有以 Redis 为后端的子系统——共享限流器、精确响应缓存和语义缓存——因为一套部署通常把它们指向同一个 Redis。1.1.0 及更早版本不发射该指标。 。类型：counter 。标签数量：1 个标签
标签
operation
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/chat/completions、/v1/messages 和 /v1/responses。其他端点每次请求只调用一个模型，请求指标已经完整描述了它们。

aisix_deployment_requests_total 。描述：下发到某个目标模型的上游尝试次数，不论结果如何。 。类型：counter 。标签数量：4 个标签
标签
provider, model, upstream_model, provider_key_id
PromQL 示例
sum(rate(aisix_deployment_requests_total[5m])) by (model)
aisix_deployment_success_responses_total 。描述：目标模型成功响应的上游尝试次数。 。类型：counter 。标签数量：4 个标签
标签
provider, model, upstream_model, provider_key_id
行为

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

aisix_deployment_failure_responses_total 。描述：在目标模型处失败的上游尝试次数，包含随后被回退救回的那些失败。 。类型：counter 。标签数量：4 个标签
标签
provider, model, upstream_model, provider_key_id
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
行为

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

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

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

aisix_deployment_state 。描述：目标模型是否参与轮转。 。类型：gauge 。标签数量：4 个标签
标签
provider, model, upstream_model, provider_key_id
指标值 的值
0, 2

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

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

安全护栏指标

跟踪所有端点上各安全护栏的执行延迟和结果，以及聚合阻断和 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 个标签
标签
env_id, guardrail, kind, phase, result, error_type
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 调用配置的 embedding 模型，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 。标签数量：无标签
标签

无。

aisix_guardrail_bypasses_total 。描述：在所有受安全护栏保护的端点上，安全护栏评估失败或网关发起的不可读内容放行中，由 fail-open 策略让请求或响应继续处理的次数。 。类型：counter 。标签数量：1 个标签
标签
reason
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 系列；被调用方中途放弃的流在这里是 4xx，在那里是 2xx，因为响应确实是以 200 开始的。看 Agent 健康度用这个系列，看路由流量用 proxy 系列。

对于流式 A2A，aisix_proxy_request_duration_seconds 记录到响应开始为止的时间。对于已下发的调用，aisix_request_e2e_latency_seconds{endpoint="/a2a"} 记录 Agent 调用的完整时长，包含完整的流。

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

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

PromQL 示例
sum by (agent, operation) (
  rate(aisix_a2a_requests_total{status!="2xx"}[5m])
)
aisix_a2a_ttfb_seconds 。描述：流式 A2A 调用中，上游 Agent 发出首个流式事件的耗时。 。类型：histogram 。标签数量：2 个标签
标签
agent, operation
行为

之所以按「事件」而非「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 个标签
标签
agent, operation
行为

除以流式操作上的 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 个标签
标签
agent, state
行为

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

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

用量事件指标

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

指标条目：5
用量事件传递

每次发送尝试的事件要么被传递到控制面，要么计为丢弃。从发送尝试速率中减去丢弃速率，即可计算传递速率。已传递的事件仍可能被控制面拒绝而未被存储，这部分由 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 一一对应，因此不会增加新的序列维度。它是控制平面上次投影该 API Key 时写入的名称，而非实时查询结果：此后成员改名，这些指标上仍会沿用旧名称，直到该 API Key 因其他原因被再次写入。

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

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

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

aisix_usage_events_emitted_total 。描述：用量事件发送尝试，在 AISIX 尝试将事件加入队列前计数，包括被队列接受的事件和被队列拒绝的事件。status 为用量事件记录的状态：在 200 响应头发出后失败的流按该失败的状态计数，例如 502、504 或 499；1.4.0 及更早版本则把大多数此类流计入 200。 。类型：counter 。标签数量：10 个标签
标签
handler, status_code, status, inbound_protocol, upstream_protocol, model, provider_key_id, provider_key_name, user_id, user_name
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, model, provider_key_id, provider_key_name, upstream_protocol, user_id, user_name
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_otlp_fanout_drops_total 。描述：导出器扇出丢失的遥测记录，按导出器和原因统计。尽管指标名里带 OTLP，它覆盖所有可观测性导出器——OTLP/HTTP、阿里云 SLS、对象存储和 Datadog——因为它们都跑在同一条扇出链路上。按记录数而非批次数计数，因此可以与导出器实际投递的数量直接对比：一个失败的批次丢失多少条记录，取决于它携带了多少条。1.1.0 及更早版本不发射该指标。 。类型：counter 。标签数量：2 个标签
标签
exporter, reason
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
行为

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
reason 的值
fetch, parse, validate

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

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

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

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

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

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

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

请检查 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 个标签
标签
kind
行为

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

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

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

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

无。

aisix_config_applied_revision 。描述：网关当前使用的配置所对应的 etcd 版本。 。类型：gauge 。标签数量：无标签
标签

无。

aisix_config_hash_info 。描述：已应用配置的哈希值。 。类型：gauge 。标签数量：1 个标签
标签
hash
指标值 的值
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
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
trigger 的值
watch, full

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

行为

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

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

网关进程指标

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

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

无。

行为

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

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

PromQL 示例
increase(aisix_log_lines_dropped_total[5m]) > 0

使用 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]))

是否将受限流的请求纳入总体取决于运维策略。若要从分母中排除已达到配额的客户端，请使用：

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——例如模型不存在、被输入安全护栏拦截、被 AISIX Cloud 预算拒绝，或请求体在转发前被拒绝。这些都是真实的失败，因此在计算成功率时应保留在分母中；只有在专门比较各上游时才应排除它们。

请勿改用 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{status_class="2xx"}[5m]))
)

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

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

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

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

比较单实例流式延迟​

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

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

# 同一批流量的 P90 响应开始延迟
aisix_llm_request_duration_seconds{endpoint="/v1/chat/completions", stream="true", quantile="0.9"}

两条查询都固定了 endpoint，因为这两个序列默认覆盖的流量并不相同：首个流式帧延迟在流式 /v1/chat/completions、/v1/messages 和 /v1/responses 上记录，而持续时间序列覆盖所有模型推理端点。不加这个过滤条件，其他模型推理端点的流量可能会影响持续时间 P90，却不会计入 TTFT P90。

aisix_llm_request_duration_seconds 在网关把响应交给客户端时记录。流式请求在这一刻还没有读取任何帧，因此该值只覆盖到响应开始为止的处理，不包含整个生成过程。它不是流式流量的端到端指标，加上 stream="true" 过滤也不会变成端到端。aisix_request_duration_seconds 和 aisix_proxy_request_duration_seconds 在同一时刻记录，同样如此。非流式流量上这三者确实覆盖完整请求。

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

对于已下发的 A2A 调用，同一直方图使用 endpoint="/a2a"，记录 Agent 调用的完整时长。已进入 A2A 统计、但在下发之前被拒绝的调用记录为零时长。对于流式调用，aisix_proxy_request_duration_seconds 在响应开始时就停止计时，而该直方图会持续到流结束；被放弃的流在 4xx 状态类中记录为 499。

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

测量安全护栏延迟和结果​

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]))

使用 kind 标签比较各类安全护栏的执行延迟。keyword 和 pii 在进程内运行；远程审核类型还包含后端调用的耗时：

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 度量，参见测量响应缓存效果。

计算支出与单请求成本​

aisix_llm_spend_micro_usd_total 以微美元计数，1 美元等于 1,000,000 微美元。除以 1e6 即可换算为美元：

# 按团队统计每小时美元支出
sum by (team_id) (rate(aisix_llm_spend_micro_usd_total[5m])) * 3600 / 1e6

# 按最近一天的速率预测 30 天支出
sum(rate(aisix_llm_spend_micro_usd_total[24h])) * 86400 * 30 / 1e6

由于支出计数器与请求计数器使用相同的标签，单请求平均成本可以直接相除。请对两侧使用相同的分组标签：

sum by (model) (rate(aisix_llm_spend_micro_usd_total[5m])) / 1e6
  /
sum by (model) (rate(aisix_llm_requests_total[5m]))

只有在 AISIX 能解析出请求价格时才会记录支出，而请求计数器会统计所有请求。若部署中存在未配置成本的模型，其流量会计入分母，使平均值偏低。请将两侧都过滤到已配置价格的模型，或逐个模型分别比较，而不要直接读取一个全局数字。

计算单请求 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])))

# 支出速率最高的十个用户，单位为每小时美元
topk(10, sum by (user_id, user_name) (rate(aisix_llm_spend_micro_usd_total[1h])) * 3600 / 1e6)

# 某个团队的支出分布在哪些模型上
sum by (model) (rate(aisix_llm_spend_micro_usd_total{team_id="team-platform"}[1h])) * 3600 / 1e6

user_name 和 provider_key_name 与各自的 ID 一一对应，因此在分组中加入名称不会增加序列数量。在控制面提供之前，user_name 报告 unknown。

测量响应缓存效果​

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 网关。AISIX Cloud 预算 Gauge 指标描述预算拒绝，并不会持续提供当前支出数据。

被限流拒绝的请求占比来自请求指标族的 outcome 标签，它覆盖所有端点：

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]))

当 AISIX Cloud 因阻断型预算超限而拒绝请求时，预算 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 指标无法在 AISIX Cloud 拒绝请求前发出预警，因为它们的值来自拒绝响应。请配置预算告警与通知，在阻断型预算开始拒绝流量前接收阈值通知。

当一把 Key 消失之后​

aisix_budget_* 和 aisix_ratelimit_remaining_* 只在处理请求的过程中写入，而 Prometheus 序列一旦产生就不会被删除。因此 AISIX 会主动让它们退休：API Key 被删除、或被改绑到其他团队或成员（这会开出一条新序列并让旧的搁浅）之后的数秒内，陈旧的样本会被改写为 NaN，aisix_budget_details_present 则写为 0。

用 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_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_seconds0.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_seconds0.05、0.1、0.25、0.5、1、2、5、10、30、60、120、300
aisix_guardrail_latency_seconds0.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_seconds0.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 部署的网关，请通过 extraEnvVars 提供逗号分隔的列表：

extraEnvVars:
  - name: AISIX_OBSERVABILITY__METRICS__BUCKETS__REQUEST_TTFT
    value: "0.005,0.01,0.025,0.05,0.1,0.5,1,5,30"
警告

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

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