令牌使用计量

简介

Agent Router 会公开遵循 OpenTelemetry GenAI 语义约定的 Prometheus 指标,其中包括每个请求的令牌使用量。通过将调用方身份添加为指标标签,并通过平台监控堆栈采集该指标,您可以统一查看各部门、命名空间和模型的令牌消耗情况。同一数据还可通过 Alauda Cost Management 支持分摊计费。

处理流程如下:网关发出令牌指标,将身份附加为标签,由 PodMonitor 将指标采集到平台中,再由 MonitorDashboard 展示该指标。日常查看无需使用原始 PromQL。

使用场景

  • 按模型向每个部门展示其自身的令牌消耗,并按项目隔离。
  • 跟踪整个​​平台中哪些模型产生了最多的令牌使用量。
  • 提供使用量数据,由 Alauda Cost Management 根据该数据生成分摊计费报告。

前提条件

  1. 已配置 AIGatewayRoute 和 llmRequestCosts 的 llmRequestCosts。请参阅配置令牌配额。如果没有配置该组件,网关仍会发出 gen_ai_client_token_usage_token,但每个请求的令牌计数都将为零。

  2. 调用方身份已作为请求标头传播。请参阅对使用者进行身份验证。

  3. 已在集群上启用平台监控。通过检查 Prometheus operator CRD 进行确认:

    kubectl get crd podmonitors.monitoring.coreos.com
  4. 在接入监控之前,先确认指标正在发出。通过网关发送一个请求,然后读取数据平面代理 Pod 上 ExtProc sidecar 的管理端口:

    POD=$(kubectl get pod -n envoy-gateway-system \
      -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name> \
      -o jsonpath='{.items[0].metadata.name}')
    kubectl port-forward -n envoy-gateway-system pod/$POD 1064:1064 &
    curl -s http://localhost:1064/metrics | grep gen_ai_client_token_usage_token | head
    # expect lines like: gen_ai_client_token_usage_token_sum{gen_ai_operation_name="chat",...} 42

    如果没有出现 gen_ai_* 样本,下面的抓取将无法工作——请先修复路由 / ExtProc 连接配置。

NOTE

请在专用命名空间(例如 maas-system)中创建 Gateway 和 AIGatewayRoute,不要在 Envoy Gateway 控制平面命名空间 envoy-gateway-system 中创建。放置在控制平面命名空间中的网关可能不会将 AI Gateway 请求处理过滤器和 SecurityPolicy 应用到其监听器,从而导致路由和策略执行静默失效。请参阅 Alauda AI Platform Gateway。

步骤

为 token 指标添加身份标签

默认情况下,token 指标 gen_ai_client_token_usage_token 只包含 OpenTelemetry GenAI 标准标签(模型、提供方、操作、token 类型)。在 Agent Router controller 中将身份标头映射到指标标签,为其添加调用方身份维度——计费命名空间和调用方部门。

controller 从 ai-gateway-controller Deployment 上的 CLI flag --metricsRequestHeaderAttributes=<header>:<label>[,<header>:<label>...] 读取映射。如果通过 Helm 安装了 controller,该 chart 会根据 values 键(例如 controller.metricsRequestHeaderAttributes)生成此 flag;请提供 release 名称和 chart 引用,然后应用 helm upgrade --reuse-values。如果直接管理 Deployment,请修补其容器参数。

此 flag 是一个由逗号连接的 <header>:<label> 映射,只能有一个,而不是可重复传入的列表:传入两次时,controller 只会保留最后一个。平台还提供了默认键值对(例如 x-user-name:user 和 x-access-meta:client_id),数据平面 sidecar 已经会发出这些键值对,因此必须用现有键值对与新增键值对的并集重写这一个 flag。遗漏任何键值对,都会在每个代理下次重启时移除对应的指标标签。

首先读取数据平面当前实际发出的键值对(代理 sidecar 是事实来源——controller flag 可能已被缩减):

PROXY=$(kubectl -n envoy-gateway-system get pod \
  -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name> \
  -o jsonpath='{.items[0].metadata.name}')
kubectl -n envoy-gateway-system get pod "$PROXY" \
  -o jsonpath='{.spec.initContainers[?(@.name=="ai-gateway-extproc")].args}' \
  | jq -r 'index("-metricsRequestHeaderAttributes") as $i | .[$i+1]'
# e.g. x-user-name:user,x-user-namespace:user_namespace,x-access-meta:client_id  (platform defaults)

然后用完整的键值对集合加上 x-user-group:department,重写 controller 的这一个 flag。将下方左侧替换为上述命令输出的内容——不要遗漏任何键值对:

# Locate the flag's argument index on the controller Deployment
IDX=$(kubectl -n envoy-gateway-system get deploy ai-gateway-controller \
  -o jsonpath='{.spec.template.spec.containers[0].args}' \
  | jq 'map(test("^--?metricsRequestHeaderAttributes=")) | index(true)')

# Replace it with the UNION of existing pairs + the new one
kubectl -n envoy-gateway-system patch deploy ai-gateway-controller --type json -p '[
  {"op":"replace","path":"/spec/template/spec/containers/0/args/'"$IDX"'",
   "value":"--metricsRequestHeaderAttributes=x-user-name:user,x-user-namespace:user_namespace,x-access-meta:client_id,x-user-group:department"}
]'
# If the flag is not present anywhere (IDX is null), add it instead with the same full value:
#   --type json -p '[{"op":"add","path":"/spec/template/spec/containers/0/args/-","value":"--metricsRequestHeaderAttributes=...,x-user-group:department"}]'

kubectl -n envoy-gateway-system rollout status deploy ai-gateway-controller

# The mapping is rendered into each data-plane proxy pod's ExtProc sidecar args
# at pod-creation time. A controller-only rollout does NOT update already-running
# proxy pods, so recreate them and wait:
kubectl rollout restart deployment -n envoy-gateway-system \
  -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name>
kubectl rollout status deployment -n envoy-gateway-system \
  -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name>
  • x-user-namespace → user_namespace:请求计费到的命名空间或租户。Chargeback with Cost Management 按此命名空间级键进行分组,因此使用 Cost Management 时请保留此键。
  • x-user-group → department:用于监控面板的低基数身份维度。由 IdP groups 声明中的 SecurityPolicy 设置。
NOTE

创建代理 Pod 时,--metricsRequestHeaderAttributes 映射会写入 ExtProc sidecar 参数中。仅修补 controller 并等待其滚动更新是不够的——必须重新创建代理 Pod(即上方的 rollout restart),新标签才会出现。如果下面的验证返回空输出,说明代理 Pod 尚未重新创建。

NOTE

user_namespace(计费命名空间)是可靠的默认分组依据——映射 x-user-namespace 后,该标签始终存在。department(x-user-group)是实用的低基数维度,但仅当 IdP 发出单值组声明时才适用(标准 OIDC groups 声明是数组,claimToHeaders 不支持,因此在其他情况下 department 会为空——请参阅对使用者进行身份验证)。避免使用按用户划分的标签(x-user-id):它会生成高基数时间序列(每个用户 × 模型 × token 类型各一条),因此只有在需要按用户报告且保留期限能限制时间序列数量时才添加。

滚动更新完成后,发送新请求并确认样本中包含新标签。user_namespace 始终存在;只有在配置了标量组声明时,department 才会出现:

curl -s http://localhost:1064/metrics | grep 'user_namespace=' | head

将指标采集到平台

此指标由 AI Gateway external processor(ExtProc)发出,它作为 sidecar 运行在每个数据平面代理 Pod 上(声明为 Kubernetes 原生 sidecar / initContainer),并在容器端口 1064(名称为 aigw-metrics)上公开 Prometheus 指标端点。平台通过 PodMonitor 直接从代理 Pod 抓取指标。平台工作流请参阅 监控管理。

在 Alauda 平台上,此 sidecar 的 PodMonitor 通常已预装。请先检查——在同一端点上配置第二个 PodMonitor 会创建重叠的抓取池,对每个代理 Pod 抓取两次,导致在不同的 job 标签下生成重复时间序列,并使监控面板和费用分摊查询中的每个 increase()/sum 都翻倍(两者都不会按 job 进行筛选):

kubectl get podmonitor -A \
  -o jsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name}{"\t"}{.spec.podMetricsEndpoints[*].port}{"\n"}{end}'
# The Alauda platform ships `ai-gateway-extproc-metrics` targeting the `aigw-metrics`
# port. If any PodMonitor already lists `aigw-metrics`, SKIP the apply below and go
# straight to the scrape check.

只有在没有现有 PodMonitor 指向 aigw-metrics 时,才查询 Prometheus operator 用于选择 PodMonitor 对象的标签(确保能实际发现下方资源),并创建一个:

kubectl get prometheus -A \
  -o jsonpath='{range .items[*]}{.metadata.namespace}/{.metadata.name}: {.spec.podMonitorSelector}{"\n"}{end}'
# On the Alauda platform this is typically: prometheus: kube-prometheus

然后,在 PodMonitor 自身的 metadata.labels 中添加该标签并应用(不要与 selector 混淆——两者是不同的内容):

apiVersion: monitoring.coreos.com/v1
kind: PodMonitor
metadata:
  name: ai-gateway-metrics
  namespace: envoy-gateway-system
  labels:
    prometheus: kube-prometheus   # must match your Prometheus's spec.podMonitorSelector
spec:
  selector:
    matchLabels:
      app.kubernetes.io/managed-by: envoy-gateway
      app.kubernetes.io/component: proxy
  podMetricsEndpoints:
    - port: aigw-metrics
      path: /metrics
      interval: 30s
  • metadata.labels:Prometheus 如何发现 PodMonitor。如果标签不正确,资源虽然存在,但抓取流程无法发现它。
  • spec.selector:匹配集群中的每个 Envoy Gateway 数据平面代理 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 端口转发到本地,并按抓取池对活动目标分组:

PROM=$(kubectl -n <prometheus-namespace> get pod -l app.kubernetes.io/name=prometheus \
  -o jsonpath='{.items[0].metadata.name}')
kubectl -n <prometheus-namespace> port-forward $PROM 9090:9090 &

# Wait ~30s after applying a PodMonitor; the operator's config-reload is async.
curl -s 'http://127.0.0.1:9090/api/v1/targets?state=active' \
  | jq '[.data.activeTargets[] | select(.labels.endpoint=="aigw-metrics")]
        | group_by(.scrapePool)
        | map({scrapePool: .[0].scrapePool, targets: length, health: .[0].health})'
# expect: exactly ONE scrape pool covering the sidecar, health="up".
# Two pools => a duplicate PodMonitor; delete the redundant one.

构建统一的使用情况监控面板

创建一个 MonitorDashboard 来展示 token 使用情况。使用命名空间、模型和部门变量,供使用者筛选;并使用 User View,确保每个项目只能查看自己的数据。平台工作流请参阅 监控面板。

在 ExtProc /metrics 端点上,指标以 Prometheus 文本格式公开,OpenTelemetry 名称会规范化为下划线形式(gen_ai_client_token_usage_token_sum,如先决条件检查中所示)。但是,平台抓取流程会使用原始 OpenTelemetry UTF-8 名称存储时间序列,并保留其中的点号。因此,在 Prometheus 中,该时间序列为 gen_ai.client.token.usage_token_sum(以及直方图的 _sum/_count/_bucket 变体),必须使用带引号的 {__name__="..."} 形式进行选择——不带引号的下划线标识符无法匹配任何内容,会返回空向量。GenAI 内置标签同样带有点号(gen_ai.request.model、gen_ai.token.type),需要使用带引号的 UTF-8 标签语法;通过标头映射的标签(例如 department 和 user_namespace)则保持为普通标识符:

CAUTION

标题面板应按 user_namespace 分组:映射 x-user-namespace 后,该标签始终存在。只有在 x-user-group 已填充时,department 标签才会出现;这要求 IdP 提供单值组声明——标准 OIDC groups 声明是数组,不受支持,因此在其他情况下,sum by (department) 会合并为一条标签值为空的时间序列。只有在确认标签存在后(grep 'department=' 有输出),才按 department 分组;否则,请在 IdP connector 中公开一个标量声明。

# Tokens per billed namespace over the last hour
sum by (user_namespace) (
  increase({__name__="gen_ai.client.token.usage_token_sum"}[1h])
)

# Top 5 models by total tokens in the last 24h
topk(5,
  sum by ("gen_ai.request.model") (
    increase({__name__="gen_ai.client.token.usage_token_sum"}[24h])
  )
)

# Output-token share per namespace (proxy for cost; output is the expensive side)
sum by (user_namespace) (
  increase({__name__="gen_ai.client.token.usage_token_sum", "gen_ai.token.type"="output"}[1h])
)

# Optional: per-department view — only once a scalar group claim is configured
# (see the caution above), otherwise this returns an empty result:
#   sum by (department) (increase({__name__="gen_ai.client.token.usage_token_sum"}[1h]))

可在 Prometheus UI 的 Status → TSDB 页面列出所有 gen_ai* 时间序列名称,或运行以下命令,以确认该指标可供查询:

curl -s 'http://127.0.0.1:9090/api/v1/label/__name__/values' \
  | jq -r '.data[]' | grep gen_ai

验证

发送几条经过身份验证、解析到不同命名空间的请求,然后在任意代理 Pod 上通过端口转发 ExtProc sidecar 的指标端口,确认指标中包含身份标签:

POD=$(kubectl get pod -n envoy-gateway-system \
  -l gateway.envoyproxy.io/owning-gateway-name=<gateway-name> \
  -o jsonpath='{.items[0].metadata.name}')
kubectl port-forward -n envoy-gateway-system pod/$POD 1064:1064 &

# Drive a couple of authenticated requests (substitute valid tokens), then read the metric.
for token in '<token-tenant-a>' '<token-tenant-b>'; do
  curl -s -o /dev/null \
    -H "Authorization: Bearer $token" \
    -H 'Content-Type: application/json' \
    -d '{"model":"my-llm","messages":[{"role":"user","content":"hi"}]}' \
    http://<gateway-address>/v1/chat/completions
done

curl -s http://localhost:1064/metrics \
  | grep 'gen_ai_client_token_usage_token_sum{' \
  | grep 'user_namespace='

预期每个计费命名空间至少有一个样本,例如:

gen_ai_client_token_usage_token_sum{user_namespace="team-a",gen_ai_request_model="my-llm",gen_ai_token_type="input",...} 184
gen_ai_client_token_usage_token_sum{user_namespace="team-b",gen_ai_request_model="my-llm",gen_ai_token_type="input",...} 91

如果配置了标量组声明,相同的样本还会包含 department= 标签(使用 grep 'department=' 检查)。打开监控面板,确认可以查看 token 使用情况,并且能够按命名空间、模型和部门筛选。

了解更多

后续步骤

收集 token 使用情况后,请配置对 Token 使用情况进行分摊计费,使用 Alauda Cost Management 按指标计价并生成各命名空间的账单。