指标参考

AISIX 以 Prometheus 文本格式暴露运维指标。Prometheus 服务器或其它兼容收集器可以抓取这些指标，用于控制面板、告警和 PromQL 查询。

默认情况下，Prometheus 指标在专用监听器 0.0.0.0:9090 的 GET /metrics 上启用。使用 observability.metrics.prometheus.enabled、observability.metrics.prometheus.addr 和 observability.metrics.prometheus.path 配置监听器。Admin API 监听器不提供指标。

指标端点按设计不进行认证，请仅向监控网络开放该监听器。

指标族会在 AISIX 首次记录观测值时注册。刚启动后抓取可能得到空响应；请先通过代理发送请求，再次抓取相应序列。

指标类型

指标类型决定数值如何变化以及应如何查询。

类型	行为
counter	累计值，在进程重启前只增不减，例如请求数或 Token 总数。使用 rate() 计算变化速率。
gauge	可增加或减少的当前值，例如进行中的请求或剩余额度。
histogram	按可配置桶统计观测值。AISIX 直方图会暴露 _bucket、_sum 和 _count 序列，可在计算百分位数前聚合。
summary	由每个 AISIX 实例计算分位数的观测值。摘要也暴露 _sum 和 _count，但分位数不能跨实例聚合。

请求指标

AISIX 提供兼容性请求计数器、LLM 流量详细计数器，以及当前进行中请求的 gauge。

详细请求计数器共享以下标签：endpoint、inbound_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。

指标	类型	标签	说明
aisix_requests_total	counter	provider、model、status、outcome	代理请求结果，是端点覆盖范围最广的兼容性序列。
aisix_llm_requests_total	counter	详细请求标签	Chat Completions 和 Messages 请求结果，包括成功和失败请求。
aisix_proxy_requests_total	counter	详细请求标签	Chat Completions 和 Messages 流量的详细请求结果。
aisix_proxy_failed_requests_total	counter	详细请求标签	outcome 不为 success 的 aisix_proxy_requests_total 子集。
aisix_proxy_in_flight_requests	gauge	endpoint、inbound_protocol	代理当前正在处理的请求，按规范化端点和入站协议分组。

outcome 标签有四种值：

值	HTTP 状态码
success	200 到 399
client_error	400 到 499，但不包括 429
rate_limited	429
upstream_error	其它所有状态码

详细请求序列还提供以下维度：

标签	说明
stream	客户端是否请求流式响应。该标签出现在详细请求计数器和摘要延迟指标上。
is_fallback	是否由故障转移目标处理请求。该标签出现在详细请求计数器上，但不出现在延迟指标上。
provider_key_name、user_name	provider_key_id 和 user_id 对应的可读名称。名称与 ID 一一对应，不会增加新的序列维度。控制面提供名称前，user_name 为 unknown。
inbound_protocol	有界协议族。Chat 和 Messages 详细序列使用 openai 和 anthropic；进行中请求 gauge 还可使用 mcp、a2a 和 realtime。

MCP 请求在进行中请求 gauge 上使用 endpoint="/mcp" 和 inbound_protocol="mcp"。A2A Agent 调用在该 gauge 上使用 endpoint="/a2a" 和 inbound_protocol="a2a"，并在 aisix_requests_total 上使用 provider="a2a" 和 model="a2a"。

延迟指标

AISIX 提供用于检查单个实例的摘要指标，以及用于跨网关实例计算延迟百分位数的分桶直方图。

两个详细持续时间摘要共享 endpoint、inbound_protocol、provider、model、upstream_model、provider_key_id、provider_key_name、api_key_id、team_id、user_id、user_name、stream、status 和 outcome 标签。首 Token 时间摘要使用相同标签，但不包含 stream、status 和 outcome。

指标	类型	标签	说明
aisix_request_duration_seconds	summary	provider、model、status	兼容性序列中的端到端请求延迟。
aisix_llm_request_duration_seconds	summary	详细持续时间标签	Chat Completions 和 Messages 请求延迟。对于流式请求，测量响应开始前的时间，而不是完整流持续时间。
aisix_proxy_request_duration_seconds	summary	详细持续时间标签	Chat Completions 和 Messages 的详细请求延迟，流式语义与 aisix_llm_request_duration_seconds 相同。
aisix_llm_time_to_first_token_seconds	summary	详细持续时间标签，但不含 stream、status 和 outcome	流式 Chat Completions 和 Messages 请求从进入网关到生成首个 Token 的时间。
aisix_request_e2e_latency_seconds	histogram	env_id、endpoint、model、provider、status_class、streaming	Chat Completions、Messages 和 Responses 的客户端感知延迟。流式请求测量完整流持续时间。
aisix_request_ttft_seconds	histogram	env_id、endpoint、model、provider、status_class、streaming	流式 Chat Completions 和 Messages 请求的首 Token 时间；streaming 始终为 true。

延迟指标类型

根据计算范围选择指标类型。

类型	适用场景	聚合行为
直方图	构建跨网关实例的服务级控制面板和告警。	_bucket、_sum 和 _count 可以跨实例和标签维度聚合。使用 histogram_quantile() 计算百分位数。
摘要	检查单个网关实例预先计算的分位数。	AISIX 固定可用分位数。分位数值不能聚合；对多个实例的 P90 求平均不能得到这些实例整体的有效 P90。

P90 是第 90 百分位数，即 90% 的观测请求延迟不高于该值。P95 或 P99 等更高百分位数会更关注最慢的请求。

两个直方图使用从 10 毫秒到 300 秒的桶边界，覆盖不足 100 毫秒的缓存命中、首 Token 时间和持续数分钟的生成。

这些标签刻意保持有界。env_id 标识托管网关服务的环境；独立网关使用 unknown。status_class 将状态分为 2xx、3xx、4xx、5xx 或 other。为控制桶序列数量，不包含每个 Key 和每个用户的标签；这些维度请使用用量分析。

每个端到端直方图观测只记录一次。非流式请求和失败在处理器返回时记录；流式请求在流结束时记录，包括客户端中途取消。取消的流会保留已提交状态，并记录取消前的持续时间。

本页其它延迟指标均为摘要。

用量与成本指标

输入、输出、总 Token 和支出计数器共享 endpoint、inbound_protocol、provider、model、upstream_model、provider_key_id、provider_key_name、api_key_id、team_id、user_id 和 user_name 标签。

指标	类型	标签	说明
aisix_tokens_consumed_total	counter	provider、model	已完成的非流式 Chat Completions 请求中 usage.total_tokens 的总和。
aisix_llm_input_tokens_total	counter	共享用量标签	上游为 Chat Completions 和 Messages 请求上报的输入 Token。
aisix_llm_output_tokens_total	counter	共享用量标签	上游上报的输出 Token。
aisix_llm_total_tokens_total	counter	共享用量标签	上游上报的总 Token。
aisix_llm_spend_micro_usd_total	counter	共享用量标签	非流式 Chat Completions 的估算支出，单位为微美元；1 美元等于 1,000,000 微美元。
aisix_llm_tokens_by_client_total	counter	client_type、token_type	按规范化客户端类型和 Token 类型分组的 Token 量。

对于 aisix_llm_tokens_by_client_total，token_type 为 input、output 或 total。total 包含输入、输出以及 Anthropic 缓存创建和缓存读取 Token。由于 Anthropic 单独上报缓存 Token，total 可能大于 input 加 output。

跨标签聚合后，该包含缓存的总量与 aisix_llm_total_tokens_total 一致。由于两个指标族使用不同标签集，单个序列不会一一对应。独立的 client_type 序列避免为每个 Key 的 Token 序列再增加一个标签维度。

AISIX 从入站 User-Agent 推导 client_type，并将其规范化到有界允许列表，客户端控制的请求头不能产生无界 Prometheus 基数。

可识别值包括 openai-python、openai-node、anthropic-python、anthropic-typescript、claude-code、codex、cline、aider、langchain、llamaindex、litellm、curl、python-requests、httpx、aiohttp、okhttp、go-http-client、node、postman、browser、other 和 unknown。未识别的 User-Agent 映射为 other，缺失时映射为 unknown。完整 User-Agent 和版本保留在请求日志与用量分析中，而不是指标标签中。

限流与预算指标

这些指标展示限流拒绝，以及每组标签最近观测到的配额或预算状态。

指标	类型	标签	说明
aisix_ratelimit_rejections_total	counter	scope	因限流而被拒绝的 Chat Completions 请求，例如 requests 或 tokens 作用域。
aisix_ratelimit_remaining_requests	gauge	api_key_id、model	API Key 和模型最近观测到的剩余请求配额。
aisix_ratelimit_remaining_tokens	gauge	api_key_id、model	API Key 和模型最近观测到的剩余 Token 配额。
aisix_budget_limit_usd	gauge	api_key_id、team_id、user_id	预算上限（美元）。
aisix_budget_spent_usd	gauge	api_key_id、team_id、user_id	已支出预算（美元）。
aisix_budget_remaining_usd	gauge	api_key_id、team_id、user_id	剩余预算（美元）。
aisix_budget_reset_seconds	gauge	api_key_id、team_id、user_id	距离预算周期重置的秒数。
aisix_budget_details_present	gauge	api_key_id、team_id、user_id	是否存在预算详情：存在时为 1，清除后为 0。

部署指标

使用部署指标监控目标模型是否仍在轮转，以及进入冷却的频率。

指标	类型	标签	说明
aisix_deployment_state	gauge	provider、model、upstream_model、provider_key_id	目标模型是否在轮转：0 表示健康；2 表示因冷却或后台健康检查失败而退出轮转；1（部分失败）为保留值，当前不会发出。
aisix_deployment_cooled_down_total	counter	provider、model、upstream_model、provider_key_id	目标模型进入冷却的次数。

安全护栏指标

安全护栏指标当前覆盖 /v1/chat/completions 请求。

指标	类型	标签	说明
aisix_guardrail_blocks_total	counter	无	被输入或输出安全护栏拒绝的请求，包括策略阻断和关闭式失败。
aisix_guardrail_bypasses_total	counter	reason	远程安全护栏不可用且 fail_open 允许请求继续时的开放式失败事件。

安全护栏绕过原因包括 bedrock_5xx、bedrock_timeout 和 bedrock_throttled。

用量事件指标

这些计数器区分用量事件发送尝试，以及投递队列未接受的事件。

指标	类型	标签	说明
aisix_usage_events_emitted_total	counter	handler、status_code、inbound_protocol	用量事件发送尝试。AISIX 在尝试入队前增加计数，因此同时包含已投递和已丢弃事件。
aisix_usage_event_drops_total	counter	reason	未被队列接受的用量事件，原因包括 sink_disabled、sink_full 和 sink_closed。

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

status_code 标签分组为 2xx、3xx、4xx、5xx 或 other。handler 标识端点族，例如 chat、embeddings、messages 或 mcp。

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

A2A Agent 调用使用 handler="a2a"。aisix_usage_events_emitted_total 上有界的 inbound_protocol 标签会把这些调用映射为 other，实际投递的事件则使用 inbound_protocol="a2a"，并标识 Agent 名称和 JSON-RPC 方法。Token 与成本字段为零。

保留的指标名称

当前 AISIX 源码保留了以下指标名称，但没有运行时路径记录它们，因此不会出现在 Prometheus 抓取结果中。在实现运行时发送前，不要基于这些指标构建控制面板或告警。

aisix_llm_api_latency_seconds 只保留了一个表示不含网关开销的上游 API 延迟名称，其指标类型、标签和记录方式尚未定义。

其余名称带有使用下列标签的 counter 记录方法，但这些方法目前没有运行时调用方：

• aisix_deployment_requests_total 使用 provider、model、upstream_model 和 provider_key_id，表示分派给目标模型的请求。
• aisix_deployment_success_responses_total 使用相同部署标签，表示目标模型成功响应。
• aisix_deployment_failure_responses_total 使用相同部署标签，表示目标模型失败响应。
• aisix_routing_successful_fallbacks_total 使用 model，表示成功故障转移到另一候选目标。
• aisix_routing_failed_fallbacks_total 使用 model，表示没有可用候选目标的故障转移。
• aisix_redis_failures_total 使用 operation，表示 Redis 失败。
• aisix_otlp_fanout_drops_total 使用 exporter 和 reason，表示扇出期间丢弃的 OTLP trace span。
• aisix_otlp_fanout_failures_total 使用 exporter，表示 OTLP trace span 投递失败。

使用 PromQL 分析指标

Prometheus 查询语言（PromQL）用于选择、计算和分组 Prometheus 收集的时序数据。配置抓取 AISIX 指标端点后，在 Prometheus 表达式浏览器或其它兼容界面中运行这些查询。

请根据要检查的流量和网关实例调整时间窗口、标签过滤条件和分组维度。

计算成功率

用成功请求速率除以总请求速率。以下查询合并五分钟窗口内的 Chat Completions 和 Messages 流量：

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

如果只分析某个 API，请添加 endpoint 过滤条件或按 endpoint 分组。

只测量主路由路径时，应在分子和分母中排除由故障转移目标处理的请求：

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

计算聚合延迟百分位数

计算百分位数前应跨网关实例合并直方图桶。在 sum by 分组中保留 le，需要细分时再添加 model 或 provider 等标签：

# P90 end-to-end latency across all matched gateway instances
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_e2e_latency_seconds_bucket{status_class="2xx"}[5m]))
)

# P90 end-to-end latency per model
histogram_quantile(
  0.90,
  sum by (le, model) (rate(aisix_request_e2e_latency_seconds_bucket{status_class="2xx"}[5m]))
)

# P90 time to first token per provider
histogram_quantile(
  0.90,
  sum by (le, provider) (rate(aisix_request_ttft_seconds_bucket[5m]))
)

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

# P90 end-to-end latency for successful streaming requests
histogram_quantile(
  0.90,
  sum by (le) (rate(aisix_request_e2e_latency_seconds_bucket{streaming="true", status_class="2xx"}[5m]))
)

对比单实例流式延迟

摘要序列为每个网关实例暴露预先计算的 quantile 标签。对比首 Token 时间和端到端延迟前，请选择一个抓取目标，以及要检查的模型或服务提供方：

# P90 time to first token for streaming requests
aisix_llm_time_to_first_token_seconds{quantile="0.9"}

# P90 end-to-end latency for the same streaming population
aisix_llm_request_duration_seconds{stream="true", quantile="0.9"}

不要跨实例平均摘要分位数。跨网关实例计算百分位数时，应使用上面的直方图查询。

按客户端计算 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]))