指标参考

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

指标目录

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

指标: 59
系列: 10

查询行为

指标类型

counter

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

gauge

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

histogram

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

summary

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

搜索指标

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

请求指标

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

指标条目：8

详细请求标签

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

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

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

inbound_protocol 是有界的协议类型集合，由端点推导得出：Anthropic 协议路由报告 anthropic；/mcp、/a2a 和 /v1/realtime 分别报告 mcp、a2a 和 realtime；其他端点均报告 openai。在途请求仪表使用相同的值。

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

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；其他所有状态均映射为 upstream_error。

行为

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

PromQL 示例

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

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

`inbound_protocol` 的值

openai, anthropic, realtime

`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 。标签数量：15 个标签

`inbound_protocol` 的值

openai, anthropic, mcp, a2a, realtime

`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 。标签数量：15 个标签

`inbound_protocol` 的值

openai, anthropic, mcp, a2a, realtime

`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 个标签

`inbound_protocol` 的值

openai, anthropic, mcp, a2a, realtime

行为

MCP 请求使用 inbound_protocol="mcp"；聚合网关使用 endpoint="/mcp"，按服务器划分的端点使用 endpoint="/mcp/{server}"。A2A 调用使用 endpoint="/a2a" 和 inbound_protocol="a2a"。

PromQL 示例

sum(aisix_proxy_in_flight_requests) by (endpoint, inbound_protocol)

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

行为

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

该指标速率上升通常意味着调用方在等待首个 Token 时放弃。请将其与相同模型的 aisix_llm_time_to_first_token_seconds 对比。

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

PromQL 示例

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

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

`inbound_protocol` 的值

openai, anthropic, mcp, a2a, realtime

`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 标识连接到 AISIX Cloud 的 AISIX 网关所服务的环境；AISIX 网关未连接 AISIX Cloud 时其值为 unknown。status_class 为 2xx、3xx、4xx、5xx 或 other。为控制分桶序列数量，不包含按密钥和按用户的标签；这些维度请使用用量分析。

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

行为

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

aisix_llm_request_duration_seconds 。描述：模型推理端点的详细请求持续时间。HTTP 流式请求记录到响应开始的时间；realtime 记录 WebSocket 会话关闭前的完整持续时间。。类型：summary 。标签数量：14 个标签

`inbound_protocol` 的值

openai, anthropic, realtime

`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 。标签数量：14 个标签

`inbound_protocol` 的值

openai, anthropic, mcp, a2a, realtime

`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 。描述：流式聊天补全和消息请求从进入网关到首个非空生成输出的时间。。类型：summary 。标签数量：11 个标签

`inbound_protocol` 的值

openai, anthropic

aisix_request_e2e_latency_seconds 。描述：客户端感知的聊天补全、消息和响应延迟，包括完整的流式传输时长。。类型：histogram 。标签数量：6 个标签

`status_class` 的值

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

`streaming` 的值

false, true

行为

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

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

PromQL 示例

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

aisix_request_ttft_seconds 。描述：流式聊天补全和消息请求的首个非空生成输出延迟。。类型：histogram 。标签数量：6 个标签

`status_class` 的值

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

`streaming` 的值

true

行为

生成输出包括非空内容、非空推理内容或工具调用增量。仅包含角色且内容为空的流式起始消息不会停止计时。

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

PromQL 示例

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

用量与成本指标

测量 Token 用量、估算支出和标准化客户端用量。

指标条目：6

哪些端点报告 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 标记。

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

`inbound_protocol` 的值

openai, anthropic, realtime

aisix_llm_output_tokens_total 。描述：上游在所有报告 Token 用量的端点中报告的输出 Token 数。。类型：counter 。标签数量：11 个标签

`inbound_protocol` 的值

openai, anthropic, realtime

aisix_llm_total_tokens_total 。描述：上游在所有报告 Token 用量的端点中报告的 Token 总数。。类型：counter 。标签数量：11 个标签

`inbound_protocol` 的值

openai, anthropic, realtime

aisix_llm_spend_micro_usd_total 。描述：以微美元计的估算支出；1 美元等于 1,000,000 微美元。网关只要能够解析请求价格，就会记录该指标。。类型：counter 。标签数量：11 个标签

`inbound_protocol` 的值

openai, anthropic, realtime

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 。标签数量：1 个标签

`scope` 的值

requests, tokens

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

`指标值` 的值

0, 1

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

缓存指标

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

指标条目：4

缓存命中率

每个被已启用缓存策略覆盖、且后端可用的请求都会记录一次 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 个标签

`outcome` 的值

hit_exact, hit_semantic, miss, bypass

bypass 表示调用方发送了 Cache-Control: no-cache，跳过了读取路径。no-store 请求同样计为 bypass。

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

`cause` 的值

resolve, embed

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

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

`op` 的值

lookup, store

部署指标

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

指标条目：7

统计的是尝试而非请求

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

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

由通过模型组下发的端点输出：/v1/chat/completions、/v1/messages 和 /v1/responses。其他端点每次请求只调用一个模型，请求指标已经完整描述了它们。

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 标签用于区分本地进程内检测（keyword、pii）和远程审核服务（其他所有种类）；result 标签用于区分 fail-open 绕过（bypassed，失败标签位于 error_type 中）与策略决策。fail-closed 的远程故障会显示为 blocked，其延迟会集中在配置的服务提供方超时时间附近。

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

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

keyword 和 pii 在进程内运行（本地检测）；其他种类均会调用远程审核服务。

`phase` 的值

input, output

`result` 的值

allowed, blocked, masked, bypassed, would_block, would_mask

bypassed 表示远程故障采用 fail-open；fail-closed 的远程故障记录为 blocked。would_block/would_mask 来自配置为 enforcement_mode: monitor 的安全护栏。

`error_type` 的值

none, aliyun_5xx, aliyun_config_error, aliyun_throttled, aliyun_timeout, azure_cs_5xx, azure_cs_config_error, azure_cs_throttled, azure_cs_timeout, bedrock_5xx, bedrock_throttled, bedrock_timeout, lakera_5xx, lakera_config_error, lakera_throttled, lakera_timeout, openai_moderation_5xx, openai_moderation_config_error, openai_moderation_throttled, openai_moderation_timeout, presidio_5xx, presidio_config_error, presidio_throttled, presidio_timeout

当 result="bypassed" 时，设置为有界失败标签（与 aisix_guardrail_bypasses_total{reason} 的值相同）；其他情况为 none。

行为

默认分桶：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 结果。仅限聊天补全请求；若要统计所有端点上各安全护栏的阻断率，请使用 aisix_guardrail_latency_seconds 的 _count 序列，并设置 result="blocked"。。类型：counter 。标签数量：无标签

`reason` 的值

aliyun_5xx, aliyun_config_error, aliyun_throttled, aliyun_timeout, azure_cs_5xx, azure_cs_config_error, azure_cs_throttled, azure_cs_timeout, bedrock_5xx, bedrock_throttled, bedrock_timeout, lakera_5xx, lakera_config_error, lakera_throttled, lakera_timeout, openai_moderation_5xx, openai_moderation_config_error, openai_moderation_throttled, openai_moderation_timeout, presidio_5xx, presidio_config_error, presidio_throttled, presidio_timeout

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 系列。请求耗时不在此重复：aisix_proxy_request_duration_seconds 已经在为该路由计时。

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

用量事件指标

区分用量事件发送尝试与传递队列未接受的事件。

指标条目：2

用量事件传递

每次发送尝试的事件要么被队列接受，要么计为丢弃。跨标签求和后，从发送尝试速率中减去丢弃速率，即可计算接受速率。

status_code 标签为 2xx、3xx、4xx、5xx 或 other。handler 示例值包括 chat、embeddings、messages 和 mcp。

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

A2A 智能体调用使用 handler="a2a"。该指标将其有界的 inbound_protocol 标签映射为 other，而传递的事件使用 inbound_protocol="a2a"，并标识智能体名称和 JSON-RPC 方法。Token 与成本字段为零。

aisix_usage_events_emitted_total 。描述：用量事件发送尝试，在 AISIX 尝试将事件加入队列前计数，包括已传递和已丢弃的事件。。类型：counter 。标签数量：3 个标签

`handler` 的值

a2a, audio, batch, batches, chat, completions, embeddings, files, fine_tuning, images, mcp, messages, passthrough, 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 。描述：未被队列接受的用量事件。。类型：counter 。标签数量：1 个标签

`reason` 的值

sink_disabled, sink_full, sink_closed

配置指标

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

指标条目：11

配置状态

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_observed_revision 。描述：网关观测到的最新 etcd 版本。。类型：gauge 。标签数量：无标签

`指标值` 的值

0, 1

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

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

`指标值` 的值

0, 1

1 表示已连接，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 调用、服务提供方透传，以及文件、批处理和微调路由），请对 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]))

计算聚合延迟百分位数

计算百分位数前，请跨网关实例合并直方图分桶。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 首个 Token 延迟
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 首个 Token 延迟
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，因为这两个序列默认覆盖的流量并不相同：首个 Token 延迟只在流式 /v1/chat/completions 和 /v1/messages 上记录，而 duration 序列覆盖所有模型推理端点——不固定 endpoint 的话，流式 /v1/responses 的流量会只影响其中一个 P90。

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

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

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

测量安全护栏延迟和结果

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 开箱即用地识别常见 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 部署的网关，请通过 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 配置模式，请参阅设置其他网关配置。

指标目录

指标类型

请求指标

标签

outcome 的值

行为

PromQL 示例

标签

inbound_protocol 的值

stream 的值

is_fallback 的值

outcome 的值

行为

标签

inbound_protocol 的值

stream 的值

is_fallback 的值

outcome 的值

行为

标签

inbound_protocol 的值

stream 的值

is_fallback 的值

outcome 的值

标签

inbound_protocol 的值

行为

PromQL 示例

标签

行为

PromQL 示例

标签

inbound_protocol 的值

outcome 的值

行为

PromQL 示例

标签

method 的值

result 的值

行为

PromQL 示例

延迟指标

标签

行为

标签

inbound_protocol 的值

stream 的值

outcome 的值

标签

inbound_protocol 的值

stream 的值

outcome 的值

标签

inbound_protocol 的值

标签

status_class 的值

streaming 的值

行为

PromQL 示例

标签

status_class 的值

streaming 的值

行为

PromQL 示例

用量与成本指标

标签

标签

inbound_protocol 的值

标签

inbound_protocol 的值

标签

inbound_protocol 的值

标签

inbound_protocol 的值

标签

client_type 的值

token_type 的值

行为

PromQL 示例

限流与预算指标

`outcome` 的值

`inbound_protocol` 的值

`stream` 的值

`is_fallback` 的值

`outcome` 的值

`inbound_protocol` 的值

`stream` 的值

`is_fallback` 的值

`outcome` 的值

`inbound_protocol` 的值

`stream` 的值

`is_fallback` 的值

`outcome` 的值

`inbound_protocol` 的值

`inbound_protocol` 的值

`outcome` 的值

`method` 的值

`result` 的值

`inbound_protocol` 的值

`stream` 的值

`outcome` 的值

`inbound_protocol` 的值

`stream` 的值

`outcome` 的值

`inbound_protocol` 的值

`status_class` 的值

`streaming` 的值

`status_class` 的值

`streaming` 的值

`inbound_protocol` 的值

`inbound_protocol` 的值

`inbound_protocol` 的值

`inbound_protocol` 的值

`client_type` 的值

`token_type` 的值

`scope` 的值

`指标值` 的值

`outcome` 的值

`cause` 的值

`op` 的值

`指标值` 的值

`kind` 的值

`phase` 的值

`result` 的值

`error_type` 的值

`reason` 的值

`handler` 的值

`status_code` 的值

`inbound_protocol` 的值

`reason` 的值

`指标值` 的值