令牌用量计量
介绍
Envoy AI Gateway 会暴露符合 OpenTelemetry GenAI 语义约定的 Prometheus 指标,其中包括每个请求的令牌用量。通过将调用方身份作为指标标签添加进来,并通过平台监控栈收集该指标,你可以按部门、命名空间和模型获得统一的令牌消耗视图。同一份数据还会被 Alauda Cost Management 用于 chargeback。
该流水线如下:网关发出令牌指标,身份作为标签附加,PodMonitor 将该指标采集到平台中,MonitorDashboard 负责展示。日常查看时无需编写原始 PromQL。
用例
- 按模型展示各部门各自的令牌消耗,并按项目隔离。
- 跟踪平台中哪些模型驱动了最多的令牌用量。
- 提供由 Alauda Cost Management 计价并写入 chargeback 报告的使用数据。
前提条件
-
一个已配置
llmRequestCosts的AIGatewayRoute。请参见 配置令牌配额。如果没有llmRequestCosts,网关仍会发出gen_ai_client_token_usage_token,但每个请求的令牌计数都将为零。 -
调用方身份已作为请求头透传。请参见 认证消费者。
-
集群已启用平台监控。可通过检查 Prometheus operator CRD 来确认:
-
在接入监控之前,先做一次健全性检查,确认指标确实已被发出。通过网关发送一个请求,然后读取数据平面 proxy pod 上 ExtProc sidecar 的管理端口:
如果没有出现任何
gen_ai_*样本,下面的任何抓取都不会生效——请先修复路由 / ExtProc 接线。
请将 Gateway 和 AIGatewayRoute 创建在专用命名空间中(例如 maas-system),而不是 Envoy Gateway 控制平面命名空间 envoy-gateway-system 中。放在控制平面命名空间里的 gateway 可能不会将 AI Gateway 请求处理 filter 和 SecurityPolicy 应用到其 listener 上,这会悄无声息地破坏路由和策略执行。请参见 Envoy AI Gateway。
步骤
为令牌指标添加身份标签
默认情况下,令牌指标 gen_ai_client_token_usage_token 只携带 OpenTelemetry GenAI 标准标签(model、provider、operation、token type)。通过在 Envoy AI Gateway controller 中将身份头映射为指标标签,可以将其扩展为调用方身份维度——即计费命名空间和调用方部门。
controller 会从 ai-gateway-controller Deployment 上的 CLI 标志 --metricsRequestHeaderAttributes=<header>:<label>[,<header>:<label>...] 读取映射。如果 controller 是通过 Helm 安装的,则 chart 会从某个 values 键(例如 controller.metricsRequestHeaderAttributes)渲染出此标志;请提供你的 release 名称和 chart 引用,并执行 helm upgrade --reuse-values。如果你直接管理 Deployment,则需要 patch 其容器参数。
该标志是一个单个由逗号连接的 <header>:<label> 映射,不是可重复列表:如果传入两次,controller 只会保留最后一份。平台还会附带一些默认配对(例如 x-user-name:user 和 x-access-meta:client_id),数据平面 sidecar 已经会发出这些配对——因此你必须用现有配对与新配对的并集重写这一个标志。若省略任何配对,下一次重启时,所有 proxy 都会失去对应的指标标签。
先读取当前数据平面实际发出的配对(proxy sidecar 才是事实来源——controller 标志可能已经被缩小过):
然后用上述完整集合再加上 x-user-group:department 重写 controller 的单个标志。请将下面左侧内容替换为上面命令实际打印出的内容——不要遗漏任何配对:
x-user-namespace→user_namespace:请求所计费到的命名空间或租户。这是 通过 Cost Management 进行 chargeback 所使用的按命名空间分组键,因此在使用 Cost Management 时应始终保留。x-user-group→department:用于监控面板的低基数身份维度。由SecurityPolicy根据 IDP 的groupsclaim 设置。
--metricsRequestHeaderAttributes 映射会在创建 proxy pod 时写入 ExtProc sidecar 参数。仅仅 patch controller 并等待其滚动更新不够——在出现新标签之前,必须重建 proxy pod(上面的 rollout restart)。如果下面的验证返回空输出,说明 proxy pod 并未重建。
user_namespace(计费命名空间)是最可靠的默认分组——只要映射了 x-user-namespace,它就一定存在。department(x-user-group)是一个有用的低基数维度,仅当 IDP 发出单值 group claim 时才可用(标准 OIDC groups claim 是数组,claimToHeaders 不支持,因此否则 department 会保持为空——请参见 认证消费者)。避免使用按用户标签(x-user-id):它会生成高基数时间序列(每个 user × model × token type 一条),因此只有在确实需要按用户报表且保留窗口能限制序列数量时才添加。
滚动更新完成后,再发送一个新请求,并确认样本上已经出现新标签。user_namespace 始终存在;只有在配置了标量 group claim 时,department 才会出现:
将指标采集到平台中
该指标由 AI Gateway external processor(ExtProc)发出,它作为每个数据平面 proxy pod 上的 sidecar 运行(声明为 Kubernetes 原生 sidecar / initContainer),并在容器端口 1064(名为 aigw-metrics)上暴露 Prometheus 指标端点。它通过 PodMonitor 直接从 proxy pod 抓取。平台工作流请参见 指标管理。
在 Alauda 平台中,这个 sidecar 的 PodMonitor 通常已经预先安装。请先检查——如果同一个端点上再创建一个 PodMonitor,会产生重叠的抓取池,导致每个 proxy pod 被抓取两次,并在不同的 job 标签下生成重复序列,同时使监控面板和 chargeback 查询中的每个 increase()/sum 都翻倍(二者都不会按 job 过滤):
只有当没有任何 PodMonitor 已经指向 aigw-metrics 时,才需要发现你的 Prometheus operator 用来选择 PodMonitor 对象的标签(这样下面的资源才会被实际采集),然后创建一个:
然后用该标签应用 PodMonitor,并将其放在自己的 metadata.labels 中(不是 selector——这两者不同):
metadata.labels:Prometheus 通过它来发现PodMonitor。如果没有正确的标签,资源虽然存在,但对抓取流水线不可见。spec.selector:匹配集群中所有 Envoy Gateway 数据平面 proxy pod。若要限制到某个Gateway,可将其替换为gateway.envoyproxy.io/owning-gateway-name: <gateway-name>和gateway.envoyproxy.io/owning-gateway-namespace: <gateway-namespace>。port: aigw-metrics:ExtProc sidecar 上的命名端口,它在容器端口1064上提供/metrics。
确认 Prometheus 正在抓取该 sidecar——并且恰好只有一个抓取池覆盖它(两个抓取池意味着重复的 PodMonitor 正在重复计数)。将 Prometheus 端口转发到本地,并按池对活动目标分组:
构建统一的使用监控面板
创建一个 MonitorDashboard 来展示令牌用量。使用 namespace、model 和 department 变量,方便使用者筛选,并依赖 User View 以确保每个 project 只能看到自己的数据。平台工作流请参见 监控面板。
在 ExtProc 的 /metrics 端点上,该指标以 Prometheus 文本格式暴露,OpenTelemetry 名称会被规范化为下划线(如上面的前置检查所示,gen_ai_client_token_usage_token_sum)。但平台抓取流水线会将序列存储为其原始 OpenTelemetry UTF-8 名称,并保留点号。因此在 Prometheus 中,该序列是 gen_ai.client.token.usage_token_sum(以及 histogram 的 _sum/_count/_bucket 变体),必须使用带引号的 {__name__="..."} 形式来选择——裸下划线标识符不会匹配任何内容,只会返回空向量。内置的 GenAI 标签同样是点号形式(gen_ai.request.model、gen_ai.token.type),需要使用带引号的 UTF-8 标签语法;而通过 header 映射得到的标签,如 department 和 user_namespace,则保持普通标识符形式:
主面板应按 user_namespace 分组:只要映射了 x-user-namespace,它就始终存在。department 标签仅当 x-user-group 有值时才会出现,这要求 IDP 提供单值 group claim——标准 OIDC groups claim 是数组,不受支持,因此否则 sum by (department) 会折叠为单个空标签序列。只有在确认标签确实存在(grep 'department=' 有输出)之后,才按 department 分组;否则应在 IDP connector 中暴露一个标量 claim。
通过在 Prometheus UI 的 Status → TSDB 页面列出所有 gen_ai* 序列名,或使用以下命令,来确认该指标可以被查询:
验证
发送几条认证请求,使其解析到不同的命名空间,然后通过为任意一个 proxy pod 的 ExtProc sidecar metrics 端口做端口转发,确认指标已携带身份标签:
预期每个计费命名空间至少有一个样本,例如:
如果你配置了标量 group claim,同样的样本还会携带 department= 标签(可用 grep 'department=' 检查)。打开监控面板并确认令牌用量已显示,且可以按 namespace、model 和 department 进行筛选。
了解更多
下一步
完成令牌用量采集后,继续配置 Charging Back Token Usage,使用 Alauda Cost Management 将该指标计价并生成按命名空间的账单。