指标标签与变量

通过 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 只生成基础部署模板；请在需要该配置的每个网关上，把 observability.metrics.labels 写入网关的配置文件，或设置上面的环境变量。请只将其应用到支持此选项的网关版本。

聚合与时间序列数量

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

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

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

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

大规模部署

除非显式配置替换列表，默认标签始终保留。API Key 或成员数量较多时，应根据实际查询和告警需求选择维度。如果不需要在 Prometheus 中按成员查询，可通过请求日志或导出的用量事件调查单次调用。

可以从以下选择开始：

• 保留服务级查询所需的 model、provider、协议、状态及结果维度。需要区分故障转移后恢复的请求时，保留 is_fallback。保留 token_type 等分类标签；删除它们会改变求和的含义。
• 如果不按调用者查询，从请求、耗时、Token 和用量事件指标中移除 api_key_id、user_id、user_name。仅在需要按团队监控的指标族中保留 team_id。
• 监控凭据健康状态时，优先使用 provider_key_id 而非凭据显示名称。名称作为标签时，改名会产生新序列。如果部署和查询需要区分环境，可添加 env_id。
• 保留预算、剩余配额、部署状态及其他 gauge 的必需身份标签。这些指标表示各个对象的当前值，删除身份会使一个对象的值覆盖另一个对象，因此网关会拒绝此类配置。

以下示例按模型及提供商凭据聚合详细流量指标，移除调用者身份和显示名称。将这些条目加入现有的 observability.metrics.labels 映射，保留其他指标族的设置。每行会替换对应指标族的完整标签列表，因此应先根据仪表盘需求调整，再重启网关。

config.yaml（可观测性配置片段）

observability:
  metrics:
    labels:
      aisix_proxy_requests_total: [endpoint, upstream_protocol, provider, model, provider_key_id, inbound_protocol, stream, is_fallback, status, outcome]
      aisix_proxy_failed_requests_total: [endpoint, upstream_protocol, provider, model, provider_key_id, inbound_protocol, stream, is_fallback, status, outcome]
      aisix_llm_requests_total: [endpoint, upstream_protocol, provider, model, provider_key_id, inbound_protocol, stream, is_fallback, status, outcome]
      aisix_proxy_request_duration_seconds: [endpoint, upstream_protocol, provider, model, provider_key_id, inbound_protocol, stream, status, outcome]
      aisix_llm_request_duration_seconds: [endpoint, upstream_protocol, provider, model, provider_key_id, inbound_protocol, stream, status, outcome]
      aisix_llm_time_to_first_token_seconds: [endpoint, upstream_protocol, provider, model, provider_key_id]
      aisix_llm_spend_micro_usd_total: [endpoint, upstream_protocol, provider, model, provider_key_id]
      aisix_llm_input_tokens_total: [endpoint, upstream_protocol, provider, model, provider_key_id]
      aisix_llm_output_tokens_total: [endpoint, upstream_protocol, provider, model, provider_key_id]
      aisix_llm_total_tokens_total: [endpoint, upstream_protocol, provider, model, provider_key_id]
      aisix_llm_cached_input_tokens_total: [endpoint, upstream_protocol, provider, model, provider_key_id]
      aisix_llm_cache_read_input_tokens_total: [endpoint, upstream_protocol, provider, model, provider_key_id]
      aisix_llm_cache_creation_input_tokens_total: [endpoint, upstream_protocol, provider, model, provider_key_id]
      aisix_usage_events_emitted_total: [handler, status_code, status, inbound_protocol, upstream_protocol, model, provider_key_id]
      aisix_usage_event_drops_total: [reason, model, provider_key_id, upstream_protocol]

此示例保留 SLO 延迟直方图的默认标签，也不修改预算和配额 gauge；这些逐对象序列仍会影响总规模。未列出的指标继续使用全部默认标签，因此还需结合实际流量检查下表中的其他指标族。

容量应按实际观测过的标签组合估算，而非只看配置数量或当前请求速率。大量不同调用者访问后，即使业务暂时空闲，累计指标序列仍然存在。每个默认耗时 summary 输出七个分位值及 sum、count：两个此类指标族各有 50,000 组标签时，仅它们就产生 900,000 行样本，尚未包括 counter 和其他指标。包含 N 个有限桶边界的 histogram，每组标签产生 N + 3 条序列。在记录前裁减标签，可以减少网关存储、维护、序列化和传输成本。Prometheus 的 metric_relabel_configs 在网关生成响应后才执行，不能消除网关侧的这些工作；在那里删除标签也不会聚合样本。

直接抓取每个网关实例，避免通过负载均衡服务轮流读取多个实例的独立计数器。可从 30 秒抓取间隔、10 秒超时开始，在预期的峰值基数下测量，包括预热后的首次抓取。超时应短于抓取间隔，间隔则应满足告警时效要求。仅增大超时不会减少序列数量或 CPU 消耗。

同时检查 scrape_duration_seconds、scrape_samples_scraped、up、网关 CPU、RSS 和请求延迟。例如，查找已入库的 AISIX 指标中序列最多的指标族：

topk(10, count by (__name__) ({job="aisix", __name__=~"aisix_.+"}))

将 job="aisix" 替换为实际抓取任务名称。修改标签后，验证新的抓取结果，更新受影响的仪表盘和告警，并等待 Prometheus 按保留策略淘汰旧序列。

支持的变量

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

变量	含义
env_id	网关所属的 AISIX Cloud 环境 ID；未连接控制面时为 unknown。所有指标均可使用。
trigger	触发一次配置应用的原因：watch 表示一批被合并处理的 watch 事件，full 表示读取全部被监听的前缀。
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	Token 类别：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_unknown_kind_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	—