基于 PromQL 与 OpenTelemetry 的 Agent 成本告警Rapid Token Burn Rate 配置全指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文以 skills 仓库中的 cost_alert_policies.md 为骨架完整讲解 Google Agent Platform 上最核心的成本告警信号——Rapid Token Burn Rate令牌快速消耗率——的配置前置条件、四种 PromQL 动态阈值算法、Terraform 落地模板与常见坑。读完本文你将掌握如何根据 Agent 的令牌使用量工作负载模式稳定 / 周期 / 突发选择正确的基线算法并用 Terraform 生成可部署的告警策略同时能借助仓库内的check_telemetry.py、analyze_traffic.py、lint_syntax.py脚本完成从数据探测到配置校验的完整闭环。一、为什么需要 Cost 告警监控 Agent 的令牌燃烧AI Agent 的推理成本与令牌消耗量直接挂钩。当 Agent 因代码缺陷、提示词退化或异常流量陷入无限循环时令牌消耗会以远超历史基线的速率飙升造成不可控的账单。Cost Alert Policies 的作用正是在令牌消耗率显著偏离历史基线时发出告警帮助你在费用失控前介入。在本仓库的 agent-platform-alert-configuration 技能中Cost 监控只定义一个告警策略即Rapid Token Burn Rate15 分钟窗口。它与 Reliability延迟、错误率 SLO、Quality在线评估器评分、Safety、Security 告警并列共同构成 Agent 平台的观测告警矩阵。需要特别强调的前置前提Cost以及 Reliability、Safety、Security告警依赖 Agent 已通过 OpenTelemetryOTel埋点上报指标。如果 Agent 没有发出gen_ai.client.token.usage指标流以下所有策略将没有数据可供评估。Agent 侧需要同时开启GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRYtrue和OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT该逻辑可从 check_telemetry.py 的源码确认。二、前置条件确定令牌使用的负载模式配置令牌监控策略之前必须先明确 Agent 的令牌使用负载模式Token Usage Workload Pattern它是选择后续算法的唯一依据。负载模式分为三类Steady / Consistent稳定 / 持续低方差、无明显的周周期性例如稳定的 QPS。Seasonal / Cyclical季节 / 周期存在明显的日/周重复形态例如每日高峰流量。Bursty / Inconsistent突发 / 不稳定高度波动伴随快速尖峰与安静期例如批处理任务型负载。2.1 用 check_telemetry 探测可用命名空间如果你尚未确定负载模式必须先运行check_telemetry工具并开启--query-monitoring-metadata标志检索令牌使用指标下所有可用的命名空间namespace并选择与目标 Agent 最接近的一个python3 scripts/check_telemetry.py \ --project_id{gcp_project} \ --location{location} \ --agent-resource-name projects/{project_id}/locations/{location}/reasoningEngines/{agent_id} \ --query-monitoring-metadata \该脚本的工作方式可以从源码得到印证check_telemetry.py它以metric.typeworkload.googleapis.com/gen_ai.client.token.usage为过滤条件查询 Cloud Monitoring以 HEADERS 视图获取时间序列描述符并提取每个序列资源标签中的namespace去重后返回。如果返回结果为空则说明该 Agent 在指定时间窗口内没有历史指标数据。两条使用规则如果用户已经在提示中提供了要使用的命名空间则无需再运行此工具如果工具没有返回相关的命名空间条目则说明该 Agent 没有可用的历史指标数据。2.2 根据历史数据可用性分流探测完成后按历史指标数据的可用性走两条分支Case 1无历史指标数据例如全新 Agent或未找到监控命名空间必须阅读并遵循 no_historical_traffic_data.md。Case 2有历史指标数据例如有流量的活跃 Agent必须阅读并遵循 has_historical_traffic_data.md。两条分支的最终目的都是回答同一个问题这个 Agent 属于哪种负载模式有历史数据运行 analyze_traffic.py 做统计分类详见下文第三节无历史数据直接询问用户期望的模式未指定时默认Steady / ConsistentShort-Window Z-Score。三、利用源码脚本完成负载模式分类当 Agent 有至少 14 天历史指标时运行流量分析脚本analyze_traffic.py进行分类。针对Rapid Token Burn Rate需要使用令牌使用指标并以其 namespace 作为引擎标识# 实时查询模式推荐 python3 scripts/analyze_traffic.py --live \ --project-id {project_id} \ --reasoning-engine-id {namespace} \ --metric-typeworkload.googleapis.com/gen_ai.client.token.usage # 从指标文件读取模式 python3 scripts/analyze_traffic.py --metrics-file {path_to_json} \ --metric-typeworkload.googleapis.com/gen_ai.client.token.usage提示如需同时对延迟Latency和令牌使用做并行流量分析可以对两个指标分别调用该工具并使用后台任务并发执行。若--live失败并报CredentialsMissingError退出码 1需让用户先运行gcloud auth application-default login。3.1 分类算法方差比与周自相关从 analyze_traffic.py 源码可见脚本对 14 天、5 分钟粒度的时序共 4032 个点计算三项统计量并做决策树分类Zero Ratio最近 7 天内速率 ≤ 0.01 的 5 分钟区间占比判断流量稀疏度Variance Ratio方差比stddev / mean衡量波动性Autocorrelation1 周自相关最近一周与上一周对应时段的相关系数衡量周周期性。决策映射规则如下表与 has_historical_traffic_data.md 一致Variance Ratiostddev/meanAutocorrelation1 周滞后流量分类对应算法与基线≤ 2.0≤ 0.75Steady / ConsistentLong-Window Z-Score1 周回看≤ 2.0 0.75Seasonal / CyclicalSeasonal Decomposition1w 与 1d 平均 2.0任意 / 不适用Bursty / InconsistentMoving Averages1 小时窗口该分类逻辑有对应的单元测试佐证analyze_traffic_test.pySEASONAL_TRAFFIC判为 Seasonal、STEADY_TRAFFIC判为 Steady1w Z-Score、BURSTY_TRAFFIC判为 BurstyMoving Averages、全零序列判为 New Agent / No TrafficShort-Window Z-Score 1h baseline。3.2 降级兜底如果脚本因数据点不足少于 14 天抛出ValueError或输出 New Agent / No Traffic则回退到用户问询流程即 no_historical_traffic_data.md直接向用户询问期望的流量模式。此外若zero_ratio 0.95即使判为 Steady应警告用户 Z-Score 告警可能不稳定建议改用 Short-Window Z-Score 或静态阈值。四、Critical Rules必须遵守的配置红线配置成本告警时以下规则是硬性约束全新 Agent无令牌使用历史必须显式询问用户期望的负载模式Steady/Consistent、Seasonal/Cyclical、Bursty/Inconsistent。如果用户要求立即配置则先提问但默认按 Steady/ConsistentShort-Window Z-Score继续执行遵循 no_historical_traffic_data.md。策略集合固定Cost 告警恰好配置一个策略——Rapid Token Burn Rate15 分钟窗口不多不少。PromQL 唯一所有 Cost 告警策略必须使用PromQL查询禁止使用 MQL 等其他语言。分组字段随资源类型变化分组字段取决于底层资源类型例如generic_node使用namespace分组。下文所有示例均假定generic_node。4.1 遥测指标信号原始指标类型描述Rapid Token Burn Rategen_ai.client.token.usageCounterAgent 消耗的令牌数量该指标经 OTel 采集后在 Cloud Monitoring 中以workload.googleapis.com/gen_ai.client.token.usage的形式出现PromQL 中因包含特殊字符__name__匹配。注意 analyze_traffic.py 对令牌指标使用resource.labels.namespace作为引擎标识对延迟指标使用metric.labels.gen_ai_agent_name二者不可混用。五、策略规格Rapid Token Burn Rate 的四种 PromQL 算法Rapid Token Burn Rate 的核心思想是比较当前短窗口的令牌使用量与历史基线偏差超过阈值即告警。所有查询都基于 95 分位histogram_quantile(0.95, ...)以降低噪声敏感度。下面给出四种算法的参数三件套短名 / 长名 / 条件描述将用于 Terraform 模板的占位符替换与完整 PromQL。5.1 Z-Score推荐用于稳定流量Z-Score 衡量当前值与历史均值的偏差是标准差的几倍。偏差 3视为异常。Long-Window Z-Score适用于有 1 周历史的成熟 Agent比较 5 分钟 95 分位令牌使用量与 1 周基线RAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_SHORT:long_window_zscoreRAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_LONG:Long-Window Z-ScoreRAPID_TOKEN_BURN_RATE_ALGORITHM_CONDITION_DESCRIPTION:Rapid Token Burn Rate Long-Window Z-Score 3abs( histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m]))) - histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[1w]))) ) / stddev_over_time( (histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m]))))[1w:5m] ) 3Short-Window Z-Score适用于有 1 小时历史的新 Agent比较 1 分钟 95 分位令牌使用量与 1 小时基线便于新 Agent 快速启用RAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_SHORT:short_window_zscoreRAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_LONG:Short-Window Z-ScoreRAPID_TOKEN_BURN_RATE_ALGORITHM_CONDITION_DESCRIPTION:Rapid Token Burn Rate Short-Window Z-Score 3abs( histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[1m]))) - histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[1h]))) ) / stddev_over_time( (histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[1m]))))[1h:1m] ) 3预热期提醒Short-Window Z-Score 需要1 小时指标历史Long-Window Z-Score 需要1 周14 天更稳妥。切换到 Seasonal Decomposition 前需警告用户会有 1 周盲区建议先用 Short-Window Z-Score 或静态阈值作为临时守卫。5.2 Moving Averages推荐用于突发流量比较 5 分钟令牌使用量与 1 小时平均值乘 1.5 作为告警触发线可平滑短期波动、避免突刺误报RAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_SHORT:moving_averageRAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_LONG:Moving AverageRAPID_TOKEN_BURN_RATE_ALGORITHM_CONDITION_DESCRIPTION:Rapid Token Burn Rate 5m window 1h avghistogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m]))) 1.5 * histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[1h])))该算法需要1 小时历史。5.3 Seasonal Decomposition推荐用于带季节 / 时段成分的流量比较 5 分钟令牌使用量与1 周前 1 天前两个基线的平均值从而规避节假日假阳性和低谷期日内误报RAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_SHORT:seasonal_decompositionRAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_LONG:Seasonal DecompositionRAPID_TOKEN_BURN_RATE_ALGORITHM_CONDITION_DESCRIPTION:Seasonal Decomposition 2histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m]))) / ( ( histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m] offset 1d))) histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m] offset 1w))) ) / 2 ) 2关于 Seasonal Decomposition 有两条极其重要的约束[!NOTE]仅用于追踪令牌使用尖峰。用 Seasonal Decomposition 同时追踪尖峰和下跌的策略可能误触发告警。[!CRITICAL]分子当前令牌使用量绝不能带 offset。offset 1d/offset 1w只能加在分母上以构造历史基线绝不可应用到第一个分子上。该算法需要1 周历史因为用到1woffset。5.4 算法选择速查负载模式推荐算法基线回看最低历史触发条件Steady / Consistent成熟Long-Window Z-Score1w 1 周建议 14 天Z-Score 3Steady / Consistent新 AgentShort-Window Z-Score1h 1 小时Z-Score 3Bursty / InconsistentMoving Averages1h1 小时5m 值 1.5 × 1h 均值Seasonal / CyclicalSeasonal Decomposition1w 与 1d 均值1 周比值 2六、Terraform HCL把 PromQL 落地为告警策略所有 Cost 告警统一使用google_monitoring_alert_policy资源配合condition_prometheus_query_language条件块。模板如下resource google_monitoring_alert_policy rapid_token_burn_rate_{rapid_token_burn_rate_algorithm_name_short} { project var.project_id display_name Agent Cost - Rapid Token Burn Rate {rapid_token_burn_rate_algorithm_name_long} combiner OR conditions { display_name {rapid_token_burn_rate_algorithm_condition_description} condition_prometheus_query_language { # Using __name__ for metric with special characters. query {rapid_token_burn_rate_telemetry_query} duration 300s # 5m buffer } } user_labels { created-with-google-skill agent-platform-alert-configuration } }模板占位符的含义{rapid_token_burn_rate_algorithm_name_short}第五节所选算法的短名{rapid_token_burn_rate_algorithm_name_long}所选算法的长名{rapid_token_burn_rate_algorithm_condition_description}所选算法的条件描述{rapid_token_burn_rate_telemetry_query}第五节选择的 PromQL 查询。6.1 与配置校验工具链的配合生成的.tf文件并非写完即止。仓库提供了 lint_syntax.py 做 HCL 语法与 PromQL 合规校验python3 scripts/lint_syntax.py {path_to_tf_file}其底层依赖 config_utils.py 中的lint_query主要检查圆括号、花括号是否平衡PromQL 时间窗口 / 子查询格式是否合法如[5m]、[1w:5m]offset格式是否合法如offset 1d查询是否引用了受支持的 agent 标识分组/过滤字段namespace或gen_ai_agent_name防止误将策略写死到单个 Agent。另有两个与本文强相关的校验细节值得注意同样来自 config_utils.pyShort-lookback PromQL 告警回看 ≤ 25 小时必须设置duration300s——这正是 Rapid Token Burn Rate 模板中写死duration 300s的原因Long-lookback 告警回看 25 小时不得设置 duration。当 PromQL 中出现1w窗口或offset 1w时Long-Window Z-Score 与 Seasonal Decomposition校验会计算最大回看小时数超过 25 小时即拒绝 duration 字段否则报错。因此若你选择的算法回看超过 25 小时Long-Window Z-Score、Seasonal Decomposition需删除或留空duration字段以通过校验若使用 Short-Window Z-Score 或 Moving Averages回看 ≤ 25 小时则必须保留duration 300s。6.2 动态分组而非写死单 Agent默认情况下告警条件不应硬编码具体的 Agent ID 或资源名过滤如gen_ai_agent_name{agent_name}除非用户明确要求只针对这个 Agent。正确做法是使用动态分组让策略覆盖项目内所有活跃 Agent# 错误示例写死单个 Agent 的过滤 sum(rate(workload_googleapis_com:gen_ai_invoke_agent_duration_count{monitored_resourcegeneric_node, gen_ai_agent_namesupport-bot}[5m]))本文所有 Rapid Token Burn Rate 查询均使用sum by (namespace,le)动态分组天然符合这一原则。七、Gotchas脚本失败与排查check_telemetry.py 意外失败首先核对参数project ID、location、agent 资源名并确认你有查看指标和 reasoning engines 的权限。注意该脚本在 telemetry 未开启时会以退出码 1 结束check_telemetry.py因此应把校验 Agent 是否已埋点作为配置告警的第一步。analyze_traffic.py 失败CredentialsMissingError退出码 1提示运行gcloud auth application-default login其他失败连接超时、权限不足、资源缺失应先分析错误信息、动态修正参数region、project ID、metric type后重试。lint_syntax.py 校验失败读取输出定位报错行分析 PromQL 语法或 HCL 结构问题并就地修正然后重新运行校验直至通过退出码 0。八、结语Rapid Token Burn Rate 是 Agent 平台成本监控的哨兵。其核心方法论可以总结为三步先探测check_telemetry→ 再分类analyze_traffic / 用户问询→ 后配置PromQL Terraform。负载模式的判定直接决定基线算法的选择而四种 PromQL 算法Long/Short Z-Score、Moving Averages、Seasonal Decomposition各有其适用场景与预热期要求Seasonal Decomposition 还需严格遵守分子不带 offset的约束。本仓库还提供了完整的校验工具链lint_syntax.pyconfig_utils.py与单元测试analyze_traffic_test.py、check_telemetry_test.py使整套配置流程从探测 → 分类 → 生成 → 校验具备可测试、可重复的执行路径。相关配套文档可进一步阅读 no_historical_traffic_data.md新 Agent 流程与 has_historical_traffic_data.md历史数据分类流程以及技能总入口 SKILL.md。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
基于 PromQL 与 OpenTelemetry 的 Agent 成本告警Rapid Token Burn Rate 配置全指南【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文以 skills 仓库中的 cost_alert_policies.md 为骨架完整讲解 Google Agent Platform 上最核心的成本告警信号——Rapid Token Burn Rate令牌快速消耗率——的配置前置条件、四种 PromQL 动态阈值算法、Terraform 落地模板与常见坑。读完本文你将掌握如何根据 Agent 的令牌使用量工作负载模式稳定 / 周期 / 突发选择正确的基线算法并用 Terraform 生成可部署的告警策略同时能借助仓库内的check_telemetry.py、analyze_traffic.py、lint_syntax.py脚本完成从数据探测到配置校验的完整闭环。一、为什么需要 Cost 告警监控 Agent 的令牌燃烧AI Agent 的推理成本与令牌消耗量直接挂钩。当 Agent 因代码缺陷、提示词退化或异常流量陷入无限循环时令牌消耗会以远超历史基线的速率飙升造成不可控的账单。Cost Alert Policies 的作用正是在令牌消耗率显著偏离历史基线时发出告警帮助你在费用失控前介入。在本仓库的 agent-platform-alert-configuration 技能中Cost 监控只定义一个告警策略即Rapid Token Burn Rate15 分钟窗口。它与 Reliability延迟、错误率 SLO、Quality在线评估器评分、Safety、Security 告警并列共同构成 Agent 平台的观测告警矩阵。需要特别强调的前置前提Cost以及 Reliability、Safety、Security告警依赖 Agent 已通过 OpenTelemetryOTel埋点上报指标。如果 Agent 没有发出gen_ai.client.token.usage指标流以下所有策略将没有数据可供评估。Agent 侧需要同时开启GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRYtrue和OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT该逻辑可从 check_telemetry.py 的源码确认。二、前置条件确定令牌使用的负载模式配置令牌监控策略之前必须先明确 Agent 的令牌使用负载模式Token Usage Workload Pattern它是选择后续算法的唯一依据。负载模式分为三类Steady / Consistent稳定 / 持续低方差、无明显的周周期性例如稳定的 QPS。Seasonal / Cyclical季节 / 周期存在明显的日/周重复形态例如每日高峰流量。Bursty / Inconsistent突发 / 不稳定高度波动伴随快速尖峰与安静期例如批处理任务型负载。2.1 用 check_telemetry 探测可用命名空间如果你尚未确定负载模式必须先运行check_telemetry工具并开启--query-monitoring-metadata标志检索令牌使用指标下所有可用的命名空间namespace并选择与目标 Agent 最接近的一个python3 scripts/check_telemetry.py \ --project_id{gcp_project} \ --location{location} \ --agent-resource-name projects/{project_id}/locations/{location}/reasoningEngines/{agent_id} \ --query-monitoring-metadata \该脚本的工作方式可以从源码得到印证check_telemetry.py它以metric.typeworkload.googleapis.com/gen_ai.client.token.usage为过滤条件查询 Cloud Monitoring以 HEADERS 视图获取时间序列描述符并提取每个序列资源标签中的namespace去重后返回。如果返回结果为空则说明该 Agent 在指定时间窗口内没有历史指标数据。两条使用规则如果用户已经在提示中提供了要使用的命名空间则无需再运行此工具如果工具没有返回相关的命名空间条目则说明该 Agent 没有可用的历史指标数据。2.2 根据历史数据可用性分流探测完成后按历史指标数据的可用性走两条分支Case 1无历史指标数据例如全新 Agent或未找到监控命名空间必须阅读并遵循 no_historical_traffic_data.md。Case 2有历史指标数据例如有流量的活跃 Agent必须阅读并遵循 has_historical_traffic_data.md。两条分支的最终目的都是回答同一个问题这个 Agent 属于哪种负载模式有历史数据运行 analyze_traffic.py 做统计分类详见下文第三节无历史数据直接询问用户期望的模式未指定时默认Steady / ConsistentShort-Window Z-Score。三、利用源码脚本完成负载模式分类当 Agent 有至少 14 天历史指标时运行流量分析脚本analyze_traffic.py进行分类。针对Rapid Token Burn Rate需要使用令牌使用指标并以其 namespace 作为引擎标识# 实时查询模式推荐 python3 scripts/analyze_traffic.py --live \ --project-id {project_id} \ --reasoning-engine-id {namespace} \ --metric-typeworkload.googleapis.com/gen_ai.client.token.usage # 从指标文件读取模式 python3 scripts/analyze_traffic.py --metrics-file {path_to_json} \ --metric-typeworkload.googleapis.com/gen_ai.client.token.usage提示如需同时对延迟Latency和令牌使用做并行流量分析可以对两个指标分别调用该工具并使用后台任务并发执行。若--live失败并报CredentialsMissingError退出码 1需让用户先运行gcloud auth application-default login。3.1 分类算法方差比与周自相关从 analyze_traffic.py 源码可见脚本对 14 天、5 分钟粒度的时序共 4032 个点计算三项统计量并做决策树分类Zero Ratio最近 7 天内速率 ≤ 0.01 的 5 分钟区间占比判断流量稀疏度Variance Ratio方差比stddev / mean衡量波动性Autocorrelation1 周自相关最近一周与上一周对应时段的相关系数衡量周周期性。决策映射规则如下表与 has_historical_traffic_data.md 一致Variance Ratiostddev/meanAutocorrelation1 周滞后流量分类对应算法与基线≤ 2.0≤ 0.75Steady / ConsistentLong-Window Z-Score1 周回看≤ 2.0 0.75Seasonal / CyclicalSeasonal Decomposition1w 与 1d 平均 2.0任意 / 不适用Bursty / InconsistentMoving Averages1 小时窗口该分类逻辑有对应的单元测试佐证analyze_traffic_test.pySEASONAL_TRAFFIC判为 Seasonal、STEADY_TRAFFIC判为 Steady1w Z-Score、BURSTY_TRAFFIC判为 BurstyMoving Averages、全零序列判为 New Agent / No TrafficShort-Window Z-Score 1h baseline。3.2 降级兜底如果脚本因数据点不足少于 14 天抛出ValueError或输出 New Agent / No Traffic则回退到用户问询流程即 no_historical_traffic_data.md直接向用户询问期望的流量模式。此外若zero_ratio 0.95即使判为 Steady应警告用户 Z-Score 告警可能不稳定建议改用 Short-Window Z-Score 或静态阈值。四、Critical Rules必须遵守的配置红线配置成本告警时以下规则是硬性约束全新 Agent无令牌使用历史必须显式询问用户期望的负载模式Steady/Consistent、Seasonal/Cyclical、Bursty/Inconsistent。如果用户要求立即配置则先提问但默认按 Steady/ConsistentShort-Window Z-Score继续执行遵循 no_historical_traffic_data.md。策略集合固定Cost 告警恰好配置一个策略——Rapid Token Burn Rate15 分钟窗口不多不少。PromQL 唯一所有 Cost 告警策略必须使用PromQL查询禁止使用 MQL 等其他语言。分组字段随资源类型变化分组字段取决于底层资源类型例如generic_node使用namespace分组。下文所有示例均假定generic_node。4.1 遥测指标信号原始指标类型描述Rapid Token Burn Rategen_ai.client.token.usageCounterAgent 消耗的令牌数量该指标经 OTel 采集后在 Cloud Monitoring 中以workload.googleapis.com/gen_ai.client.token.usage的形式出现PromQL 中因包含特殊字符__name__匹配。注意 analyze_traffic.py 对令牌指标使用resource.labels.namespace作为引擎标识对延迟指标使用metric.labels.gen_ai_agent_name二者不可混用。五、策略规格Rapid Token Burn Rate 的四种 PromQL 算法Rapid Token Burn Rate 的核心思想是比较当前短窗口的令牌使用量与历史基线偏差超过阈值即告警。所有查询都基于 95 分位histogram_quantile(0.95, ...)以降低噪声敏感度。下面给出四种算法的参数三件套短名 / 长名 / 条件描述将用于 Terraform 模板的占位符替换与完整 PromQL。5.1 Z-Score推荐用于稳定流量Z-Score 衡量当前值与历史均值的偏差是标准差的几倍。偏差 3视为异常。Long-Window Z-Score适用于有 1 周历史的成熟 Agent比较 5 分钟 95 分位令牌使用量与 1 周基线RAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_SHORT:long_window_zscoreRAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_LONG:Long-Window Z-ScoreRAPID_TOKEN_BURN_RATE_ALGORITHM_CONDITION_DESCRIPTION:Rapid Token Burn Rate Long-Window Z-Score 3abs( histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m]))) - histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[1w]))) ) / stddev_over_time( (histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m]))))[1w:5m] ) 3Short-Window Z-Score适用于有 1 小时历史的新 Agent比较 1 分钟 95 分位令牌使用量与 1 小时基线便于新 Agent 快速启用RAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_SHORT:short_window_zscoreRAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_LONG:Short-Window Z-ScoreRAPID_TOKEN_BURN_RATE_ALGORITHM_CONDITION_DESCRIPTION:Rapid Token Burn Rate Short-Window Z-Score 3abs( histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[1m]))) - histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[1h]))) ) / stddev_over_time( (histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[1m]))))[1h:1m] ) 3预热期提醒Short-Window Z-Score 需要1 小时指标历史Long-Window Z-Score 需要1 周14 天更稳妥。切换到 Seasonal Decomposition 前需警告用户会有 1 周盲区建议先用 Short-Window Z-Score 或静态阈值作为临时守卫。5.2 Moving Averages推荐用于突发流量比较 5 分钟令牌使用量与 1 小时平均值乘 1.5 作为告警触发线可平滑短期波动、避免突刺误报RAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_SHORT:moving_averageRAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_LONG:Moving AverageRAPID_TOKEN_BURN_RATE_ALGORITHM_CONDITION_DESCRIPTION:Rapid Token Burn Rate 5m window 1h avghistogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m]))) 1.5 * histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[1h])))该算法需要1 小时历史。5.3 Seasonal Decomposition推荐用于带季节 / 时段成分的流量比较 5 分钟令牌使用量与1 周前 1 天前两个基线的平均值从而规避节假日假阳性和低谷期日内误报RAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_SHORT:seasonal_decompositionRAPID_TOKEN_BURN_RATE_ALGORITHM_NAME_LONG:Seasonal DecompositionRAPID_TOKEN_BURN_RATE_ALGORITHM_CONDITION_DESCRIPTION:Seasonal Decomposition 2histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m]))) / ( ( histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m] offset 1d))) histogram_quantile(0.95,sum by (namespace,le)(increase({__name__workload_googleapis_com:gen_ai_client_token_usage_bucket,monitored_resourcegeneric_node}[5m] offset 1w))) ) / 2 ) 2关于 Seasonal Decomposition 有两条极其重要的约束[!NOTE]仅用于追踪令牌使用尖峰。用 Seasonal Decomposition 同时追踪尖峰和下跌的策略可能误触发告警。[!CRITICAL]分子当前令牌使用量绝不能带 offset。offset 1d/offset 1w只能加在分母上以构造历史基线绝不可应用到第一个分子上。该算法需要1 周历史因为用到1woffset。5.4 算法选择速查负载模式推荐算法基线回看最低历史触发条件Steady / Consistent成熟Long-Window Z-Score1w 1 周建议 14 天Z-Score 3Steady / Consistent新 AgentShort-Window Z-Score1h 1 小时Z-Score 3Bursty / InconsistentMoving Averages1h1 小时5m 值 1.5 × 1h 均值Seasonal / CyclicalSeasonal Decomposition1w 与 1d 均值1 周比值 2六、Terraform HCL把 PromQL 落地为告警策略所有 Cost 告警统一使用google_monitoring_alert_policy资源配合condition_prometheus_query_language条件块。模板如下resource google_monitoring_alert_policy rapid_token_burn_rate_{rapid_token_burn_rate_algorithm_name_short} { project var.project_id display_name Agent Cost - Rapid Token Burn Rate {rapid_token_burn_rate_algorithm_name_long} combiner OR conditions { display_name {rapid_token_burn_rate_algorithm_condition_description} condition_prometheus_query_language { # Using __name__ for metric with special characters. query {rapid_token_burn_rate_telemetry_query} duration 300s # 5m buffer } } user_labels { created-with-google-skill agent-platform-alert-configuration } }模板占位符的含义{rapid_token_burn_rate_algorithm_name_short}第五节所选算法的短名{rapid_token_burn_rate_algorithm_name_long}所选算法的长名{rapid_token_burn_rate_algorithm_condition_description}所选算法的条件描述{rapid_token_burn_rate_telemetry_query}第五节选择的 PromQL 查询。6.1 与配置校验工具链的配合生成的.tf文件并非写完即止。仓库提供了 lint_syntax.py 做 HCL 语法与 PromQL 合规校验python3 scripts/lint_syntax.py {path_to_tf_file}其底层依赖 config_utils.py 中的lint_query主要检查圆括号、花括号是否平衡PromQL 时间窗口 / 子查询格式是否合法如[5m]、[1w:5m]offset格式是否合法如offset 1d查询是否引用了受支持的 agent 标识分组/过滤字段namespace或gen_ai_agent_name防止误将策略写死到单个 Agent。另有两个与本文强相关的校验细节值得注意同样来自 config_utils.pyShort-lookback PromQL 告警回看 ≤ 25 小时必须设置duration300s——这正是 Rapid Token Burn Rate 模板中写死duration 300s的原因Long-lookback 告警回看 25 小时不得设置 duration。当 PromQL 中出现1w窗口或offset 1w时Long-Window Z-Score 与 Seasonal Decomposition校验会计算最大回看小时数超过 25 小时即拒绝 duration 字段否则报错。因此若你选择的算法回看超过 25 小时Long-Window Z-Score、Seasonal Decomposition需删除或留空duration字段以通过校验若使用 Short-Window Z-Score 或 Moving Averages回看 ≤ 25 小时则必须保留duration 300s。6.2 动态分组而非写死单 Agent默认情况下告警条件不应硬编码具体的 Agent ID 或资源名过滤如gen_ai_agent_name{agent_name}除非用户明确要求只针对这个 Agent。正确做法是使用动态分组让策略覆盖项目内所有活跃 Agent# 错误示例写死单个 Agent 的过滤 sum(rate(workload_googleapis_com:gen_ai_invoke_agent_duration_count{monitored_resourcegeneric_node, gen_ai_agent_namesupport-bot}[5m]))本文所有 Rapid Token Burn Rate 查询均使用sum by (namespace,le)动态分组天然符合这一原则。七、Gotchas脚本失败与排查check_telemetry.py 意外失败首先核对参数project ID、location、agent 资源名并确认你有查看指标和 reasoning engines 的权限。注意该脚本在 telemetry 未开启时会以退出码 1 结束check_telemetry.py因此应把校验 Agent 是否已埋点作为配置告警的第一步。analyze_traffic.py 失败CredentialsMissingError退出码 1提示运行gcloud auth application-default login其他失败连接超时、权限不足、资源缺失应先分析错误信息、动态修正参数region、project ID、metric type后重试。lint_syntax.py 校验失败读取输出定位报错行分析 PromQL 语法或 HCL 结构问题并就地修正然后重新运行校验直至通过退出码 0。八、结语Rapid Token Burn Rate 是 Agent 平台成本监控的哨兵。其核心方法论可以总结为三步先探测check_telemetry→ 再分类analyze_traffic / 用户问询→ 后配置PromQL Terraform。负载模式的判定直接决定基线算法的选择而四种 PromQL 算法Long/Short Z-Score、Moving Averages、Seasonal Decomposition各有其适用场景与预热期要求Seasonal Decomposition 还需严格遵守分子不带 offset的约束。本仓库还提供了完整的校验工具链lint_syntax.pyconfig_utils.py与单元测试analyze_traffic_test.py、check_telemetry_test.py使整套配置流程从探测 → 分类 → 生成 → 校验具备可测试、可重复的执行路径。相关配套文档可进一步阅读 no_historical_traffic_data.md新 Agent 流程与 has_historical_traffic_data.md历史数据分类流程以及技能总入口 SKILL.md。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
