指标标签与变量

通过 observability.metrics.labels 配置每个 Prometheus 指标族的完整标签列表，既可以添加可用变量，也可以删除默认标签。1.1.0 及更早版本的网关不支持此配置项。

配置标签

config.yaml

observability:
  metrics:
    labels:
      aisix_request_ttft_seconds:
        - env_id
        - endpoint
        - model
        - provider
        - status_class
        - streaming
        - provider_key_name
      aisix_proxy_requests_total:
        - endpoint
        - status
      aisix_requests_total: []

此示例为 TTFT 添加所选提供商凭据的名称。详细请求计数器仅保留入口和状态码。旧版请求计数器的全部业务标签被删除。

• 未配置的指标保留现有默认标签。labels: {} 保持所有指标的默认输出。
• 每个列表都会替换对应指标的默认列表。如果该指标没有必须保留的身份标签，空列表会删除全部业务标签。
• 使用指标族名称，例如 aisix_request_ttft_seconds，不要添加 _bucket、_sum 或 _count 后缀。直方图的各个组成部分始终使用相同的标签；Prometheus 自动添加的 le 和摘要的 quantile 不受此配置影响。
• 指标名未知、变量不适用于该指标、变量重复或删除必要身份标签时，网关会报告配置错误并拒绝启动。
• 标签在启动时确定，修改后需要重启网关。Prometheus 已存储的序列按其保留策略继续存在；依赖已删除标签的查询和告警也需要相应调整。

通过环境变量配置时，用一个 JSON 对象设置整个映射：

export AISIX_OBSERVABILITY__METRICS__LABELS='{"aisix_request_ttft_seconds":["model","provider_key_name"]}'

在 AISIX Cloud 的数据平面安装卡片中展开指标标签，即可选择指标和标签。生成的 Docker、Compose、Helm 和 systemd 安装指令会包含此启动配置。请将配置应用到支持此功能的网关版本。

聚合与时间序列数量

删除标签会在累计观测值之前合并计数器和直方图分布。例如，删除 model 后会合并不同模型的请求，而不是保留某个模型的最后一个样本。标签配置不会改变指标原本统计的请求或尝试范围。

Gauge 表示当前状态，例如某个凭据的剩余额度或某个部署的健康状态。下表列出的必要身份标签必须保留，避免不同对象的值互相覆盖。其他 gauge 标签仍可增减。

每组不同的标签值都会产生独立时间序列。凭据名称、API 密钥 ID 和成员身份可能显著增加序列数量。传统直方图针对每组标签值，分别为有限边界桶、+Inf 桶、_sum 和 _count 创建序列。请只选择查询所需的维度。

删除分类标签也会合并其各个类别。例如，token_type="total" 已包含输入与输出；删除 token_type 会累加三个类别，不能再把结果解释成原来的词元总量。

支持的变量

变量名就是输出的标签名。变量是否可用取决于指标；下表分别列出默认标签和额外支持的变量。请求归属缺失时使用 unknown；已有指标明确约定的其他缺省类别保持不变。没有请求上下文的后台指标不能使用请求变量。不支持任意请求头或表达式。

变量	含义
env_id	网关所属的 AISIX Cloud 环境 ID；未连接控制面时为 unknown。所有指标均可使用。
endpoint	匹配到的路由模板，不含调用方传入的动态路径参数。
inbound_protocol	调用方使用的协议，由匹配的入口确定。
upstream_protocol	所选提供商凭据对应的上游协议；尚未选择上游或非 LLM 请求时为 unknown。
provider	本次观测归属的提供商类型；集成模型没有唯一提供商时为 ensemble。
model	指标归属的网关模型配置标识。通配符请求使用配置中的模式；请求或尝试的归属范围见指标参考。
upstream_model	上游模型标识。通配符请求使用配置中的模式，避免调用方生成无限多种标签值。
provider_key_id	所选提供商凭据的 ID，不包含密钥内容。
provider_key_name	同一提供商凭据的显示名称；重命名后会产生新的时间序列。
api_key_id	用于认证的网关 API 密钥 ID，不包含明文密钥。
team_id	认证所用 API 密钥关联的团队。
user_id	认证所用 API 密钥关联的成员。
user_name	API 密钥配置快照中的成员显示名称。
stream	是否请求流式响应，取值 true 或 false；用于详细请求指标。
streaming	是否为流式请求，取值 true 或 false；用于请求延迟直方图。
is_fallback	请求归属是否为回退尝试，取值 true 或 false。
status	请求和使用事件指标中的 HTTP 状态码；A2A 指标中表示状态码类别。
status_class	HTTP 状态码类别：2xx、3xx、4xx、5xx 或 other。
status_code	使用事件指标中的 HTTP 状态码类别；同类指标的 status 标签保留具体状态码。
outcome	指标定义的结果，例如请求结果、缓存决策或请求体大小限制结果。
client_type	由内置规则或 client_type_rules 识别的客户端名称，不使用原始 User-Agent。
token_type	词元类别：input、output 或 total；total 已包含 input 和 output。
fallback_model	路由回退归属的模型配置名称。
scope	限流决策的作用域。
layer	限流决策的层级。
policy_id	限流策略 ID，或该指标约定的缺省策略值。
reason	认证、安全防护、配置或导出器指标定义的有限原因代码。
method	凭据认证所使用的方法。
result	指标定义的认证或安全防护执行结果。
guardrail	安全防护配置的名称。
kind	安全防护指标中的防护类型，或配置指标中的资源类型。
phase	安全防护执行阶段。
error_type	有限的安全防护错误类别；无错误时为 none。
handler	使用事件的处理入口族，例如 chat、messages、embeddings 或 mcp。
policy	缓存策略配置的名称。
cause	语义缓存向量化失败的有限原因类别。
op	语义缓存的存储操作。
operation	指标定义的 Redis 操作或 A2A 操作。
exporter	可观测性导出器配置的名称。
agent	已注册的 A2A 智能体名称。
state	上游智能体报告的 A2A 任务状态。
hash	网关已应用资源配置的哈希值。

各指标可用的变量

所有指标均可添加 env_id。所有默认标签都属于可选变量。额外变量列表示默认标签以外可以添加的变量；短横线表示没有。配置替换列表时必须包含必要身份标签。

指标族	默认标签	额外变量	必要身份标签
aisix_requests_total	provider, model, status, outcome	env_id	—
aisix_request_duration_seconds	provider, model, status	env_id	—
aisix_ratelimit_rejections_total	scope, layer, policy_id	env_id	—
aisix_tokens_consumed_total	provider, model	env_id	—
aisix_llm_spend_micro_usd_total	endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name	env_id	—
aisix_llm_input_tokens_total	endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name	env_id	—
aisix_llm_output_tokens_total	endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name	env_id	—
aisix_llm_total_tokens_total	endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name	env_id	—
aisix_llm_cached_input_tokens_total	endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name	env_id	—
aisix_llm_cache_read_input_tokens_total	endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name	env_id	—
aisix_llm_cache_creation_input_tokens_total	endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name	env_id	—
aisix_llm_requests_total	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	env_id	—
aisix_llm_request_duration_seconds	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	is_fallback, env_id	—
aisix_llm_time_to_first_token_seconds	endpoint, inbound_protocol, upstream_protocol, provider, model, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name	env_id	—
aisix_llm_tokens_by_client_total	client_type, model, token_type	env_id	—
aisix_proxy_in_flight_requests	endpoint, inbound_protocol	env_id	endpoint
aisix_proxy_requests_total	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	env_id	—
aisix_proxy_failed_requests_total	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	env_id	—
aisix_proxy_request_duration_seconds	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	is_fallback, env_id	—
aisix_proxy_client_cancelled_requests_total	endpoint, model, provider_key_id, provider_key_name	env_id	—
aisix_proxy_request_body_limit_rejections_total	endpoint, inbound_protocol, outcome	env_id	—
aisix_deployment_requests_total	provider, model, upstream_model, provider_key_id	env_id	—
aisix_deployment_success_responses_total	provider, model, upstream_model, provider_key_id	env_id	—
aisix_deployment_failure_responses_total	provider, model, upstream_model, provider_key_id	env_id	—
aisix_deployment_state	provider, model, upstream_model, provider_key_id	env_id	provider, model, upstream_model, provider_key_id
aisix_deployment_cooled_down_total	provider, model, upstream_model, provider_key_id	env_id	—
aisix_routing_successful_fallbacks_total	model, fallback_model	env_id	—
aisix_routing_failed_fallbacks_total	model, fallback_model	env_id	—
aisix_ratelimit_remaining_requests	api_key_id, model	env_id	api_key_id, model
aisix_ratelimit_remaining_tokens	api_key_id, model	env_id	api_key_id, model
aisix_budget_limit_usd	api_key_id, team_id, user_id, user_name	env_id	api_key_id, team_id, user_id, user_name
aisix_budget_spent_usd	api_key_id, team_id, user_id, user_name	env_id	api_key_id, team_id, user_id, user_name
aisix_budget_remaining_usd	api_key_id, team_id, user_id, user_name	env_id	api_key_id, team_id, user_id, user_name
aisix_budget_reset_seconds	api_key_id, team_id, user_id, user_name	env_id	api_key_id, team_id, user_id, user_name
aisix_budget_details_present	api_key_id, team_id, user_id, user_name	env_id	api_key_id, team_id, user_id, user_name
aisix_redis_failures_total	operation	env_id	—
aisix_usage_event_drops_total	reason, model, provider_key_id, provider_key_name, user_id, user_name, upstream_protocol	env_id	—
aisix_guardrail_blocks_total	—	env_id	—
aisix_guardrail_bypasses_total	reason	env_id	—
aisix_auth_decisions_total	method, result, reason	env_id	—
aisix_guardrail_latency_seconds	env_id, guardrail, kind, phase, result, error_type	—	—
aisix_usage_events_emitted_total	handler, status_code, status, inbound_protocol, upstream_protocol, model, provider_key_id, provider_key_name, user_id, user_name	env_id	—
aisix_cache_requests_total	policy, outcome	env_id	—
aisix_cache_semantic_embedding_seconds	policy	env_id	—
aisix_cache_semantic_embedding_failures_total	policy, cause	env_id	—
aisix_cache_semantic_store_failures_total	policy, op	env_id	—
aisix_otlp_fanout_drops_total	exporter, reason	env_id	—
aisix_otlp_fanout_failures_total	exporter	env_id	—
aisix_request_e2e_latency_seconds	env_id, endpoint, model, provider, status_class, streaming	inbound_protocol, upstream_protocol, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name	—
aisix_request_ttft_seconds	env_id, endpoint, model, provider, status_class, streaming	inbound_protocol, upstream_protocol, upstream_model, provider_key_id, provider_key_name, api_key_id, team_id, user_id, user_name	—
aisix_a2a_requests_total	agent, operation, status	env_id	—
aisix_a2a_ttfb_seconds	agent, operation	env_id	—
aisix_a2a_stream_events_total	agent, operation	env_id	—
aisix_a2a_task_state_total	agent, state	env_id	—
aisix_config_last_reload_successful	—	env_id	—
aisix_config_last_reload_success_timestamp_seconds	—	env_id	—
aisix_config_reloads_total	—	env_id	—
aisix_config_reload_failures_total	reason	env_id	—
aisix_config_rejected_resources	kind	env_id	kind
aisix_config_partially_compatible_resources	kind	env_id	kind
aisix_config_stale_served_resources	kind	env_id	kind
aisix_config_observed_revision	—	env_id	—
aisix_config_applied_revision	—	env_id	—
aisix_config_hash_info	hash	env_id	hash
aisix_config_source_connected	—	env_id	—