基于历史流量数据为 Agent 配置告警策略agent-platform-alert-configuration 流量分类与算法选型实战【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills本文是 Google Agent Skills 开源仓库中agent-platform-alert-configuration技能的专项实战指南聚焦Agent 已具备历史指标数据这一场景如何通过流量分析脚本将 14 天 OpenTelemetry 指标时间序列分类为 Steady / Seasonal / Bursty 三种流量画像并据此为延迟、Token 消耗等指标选择最稳健的动态阈值告警算法最终输出 Terraform.tf告警配置。读完本文你将掌握analyze_traffic.py的完整用法、分类决策树的统计原理变异系数、自相关、零值率以及流量画像 → 告警算法的映射规则与降级回退路径。一、适用场景与前置条件has_historical_traffic_data.md是agent-platform-alert-configuration技能在Case 2历史指标数据可用场景下的操作手册。与之相对若 Agent 是全新部署、没有任何历史指标应改走 no_historical_traffic_data.md 的用户询问流程。两个分支共同服务于同一目标为延迟Latency与 Token 消耗Rapid Token Burn Rate这类天然稀疏、随流量波动的指标选择统计意义上最稳定的动态阈值算法避免误报或盲区。1.1 遥测前提OTel 指标是告警的数据源该技能为 Reliability、Cost、Safety、Security 四类告警均依赖 Agent 通过 OpenTelemetry 导出指标。若 Agent 未埋点输出 OTel metrics则告警策略没有任何数据流可供评估这一点在 SKILL.md 的前置条件中已被明确声明。Quality 类告警则依赖 Vertex AI Online Monitors严格绑定 Vertex AI 部署不适用本分支。1.2 环境准备安装 Python 依赖在运行本分支的任何脚本前必须先安装脚本依赖对应 requirements.txt其中包含google-cloud-monitoring2.31.0、google-auth2.55.2等pip install -r skills/cloud/agent-platform-alert-configuration/scripts/requirements.txt1.3 明确的项目边界技能要求只允许在用户显式提供的 Google Cloud 项目上查询遥测与配置告警不得从环境或历史记录中假设其他项目Metric Scope 的判定是否多项目监控范围、scoping project 是谁由主技能中的gather_agent_info.py及gcloud beta monitoring metrics-scopes list负责本文不再赘述。二、运行流量分析脚本analyze_traffic.py本分支的第一步是运行 analyze_traffic.py对 Agent 的指标流量画像进行分类。该脚本的模块 docstring 写明了其设计目标在 5 分钟粒度的 14 天指标时间序列上计算零值率zero-ratio、变异系数variance ratio与1 周滞后自相关1-week autocorrelation从而推荐最优的动态 PromQL 告警阈值策略。2.1 按目标策略选择参数Gather arguments调用脚本时--metric-type与--reasoning-engine-id的取值取决于你正在为哪类策略做分析目标策略--metric-type--reasoning-engine-idLatency延迟workload.googleapis.com/gen_ai.invoke_agent.durationAgent 的metric.labels.gen_ai_agent_name值Rapid Token Burn RateToken 快速消耗workload.googleapis.com/gen_ai.client.token.usageAgent 的resource.labels.namespace值这一映射并非随意约定而是硬编码在源码的_SUPPORTED_METRIC_TYPE_LABEL字典中analyze_traffic.py_SUPPORTED_METRIC_TYPE_LABEL { workload.googleapis.com/gen_ai.invoke_agent.duration: ( metric.labels.gen_ai_agent_name ), workload.googleapis.com/gen_ai.client.token.usage: ( resource.labels.namespace ), }即延迟指标按gen_ai_agent_name过滤与分组Token 指标则按命名空间过滤与分组。同一个字典还定义了对应的聚合器aligner——两种指标均使用ALIGN_DELTAanalyze_traffic.py配合REDUCE_SUM跨序列归约和 300 秒5 分钟对齐周期最终得到每 5 分钟一个采样点的速率序列。2.2 两种运行模式Running the tool脚本支持两种数据来源① 实时查询模式Live Query——直接从 Cloud Monitoring 拉取目标 Agent 最近 14 天的指标python3 skills/cloud/agent-platform-alert-configuration/scripts/analyze_traffic.py --live \ --project-id {project_id} \ --reasoning-engine-id {reasoning_engine_id} \ --metric-type{metric_type}② 指标文件模式Metrics File——从本地 JSON 文件或 stdin用-指定读取数字列表python3 skills/cloud/agent-platform-alert-configuration/scripts/analyze_traffic.py --metrics-file {path_to_json} --metric-type{metric_type}在文件模式下数据必须是 JSON 数字列表脚本入口处会校验isinstance(data, list)否则以错误码 1 退出。实时模式在内部调用query_live_metrics()analyze_traffic.py它构造TimeIntervalnow - 14 * 24 * 3600秒到当前时间拼装metric.type ... AND label ...过滤条件然后通过MetricServiceClient.list_time_series拉取 FULL 视图时间序列若全程无任何数据点则直接返回一个 14 天、全为 0.0 的网格。并行流量分析如果你需要同时为 Latency 与 Token Usage 两个指标做实时分析应使用后台任务并发调用脚本而非串行等待。2.3 失败处理Handling Tool FailuresCredentialsMissingError退出码 1实时查询模式下若未找到有效的 Google Cloud 凭据脚本会抛出该自定义异常源码中在捕获auth_exceptions.DefaultCredentialsError后包装抛出见 analyze_traffic.py。此时应把错误报告给用户并指引其在终端执行gcloud auth application-default login完成本地环境认证。其他意外失败如连接超时、权限不足或资源缺失应仔细分析错误信息尝试动态修正参数如核对/纠正 region、project ID 或 metric type后重试再考虑升级处理而不是直接放弃。三、分类决策树三个统计指标与四类输出脚本会把 14 天4032 个 5 分钟点即2 * _POINTS_PER_WEEK其中_POINTS_PER_WEEK 2016见 analyze_traffic.py的时间序列切分为最近 7 天与前一个 7 天两个周窗口并计算三个关键统计量Zero Ratio零值率最近 7 天中速率 ≤ 0.01 的 5 分钟区间占比衡量流量稀疏程度Variance Ratio变异系数stddev_last / mean_last当均值 0.0001 时计算否则强制置 0衡量流量波动剧烈程度Autocorrelation at 1-week lag1 周滞后自相关最近 7 天与前 7 天的皮尔逊式协方差归一化值衡量每周同期的重复性昼夜/周末周期性。3.1 决策树逻辑源码视角分类逻辑实现在compute_metrics_and_classify()analyze_traffic.py其决策顺序为if mean_last 0.0 and zero_ratio 1.0: profile New Agent / No Traffic # 无任何流量 elif variance_ratio 2.0: profile Bursty / Inconsistent # 高波动 elif autocorr_1w 0.75 and variance_ratio 2.0: profile Seasonal / Cyclical # 强周周期性 else: profile Steady / Consistent # 低波动、弱周期性值得注意的是脚本输出可能包含5 种结果除文档决策表中的 3 种画像外还有New Agent / No Traffic全零序列推荐 Short-Window Z-Score 快速激活以及数据点不足少于 14 天直接抛出的ValueErrorInsufficient data points: expected at least 4032 (14 days at 5m interval)。3.2 决策映射参考表文档给出的核心决策表在 has_historical_traffic_data.md 中如下它是选择 Latency 告警算法的权威依据变异系数std_dev / mean1 周滞后自相关流量分类分配的 Latency 算法与基线≤ 2.0≤ 0.75Steady / ConsistentLong-Window Z-Score1 周回看≤ 2.0 0.75Seasonal / CyclicalSeasonal Decomposition1w 与 1d 均值 2.0任意 / 不适用Bursty / InconsistentMoving Averages1 小时窗口3.3 三类画像的直观示例Steady / Consistent平稳一致低方差数据如稳定的 QPS几乎没有每周周期性模式。测试用例test_classify_steady使用 mock_traffic_data.py 中围绕 50 左右小幅波动的序列验证了该分类analyze_traffic_test.py。Seasonal / Cyclical季节/周期具有清晰的日/周重复模式每周相关度高如每日高峰流量。测试用例test_classify_seasonal使用一段从低到高再到低、呈日周期起伏的序列验证analyze_traffic_test.py。Bursty / Inconsistent突发/不稳定高波动数据快速尖峰与静默期交替如批处理任务负载。test_classify_bursty用高值尖峰 近零基线的序列验证analyze_traffic_test.py。测试文件还覆盖了边界情况常量流量判为 Steady单个尖峰0.5因均值足够大使变异系数约 44.88 判为 Bursty而极小的单尖峰0.05因均值被压到 0.0001 以下、变异系数强制为 0 而回退为 Steadyanalyze_traffic_test.py。理解这些边界有助于解释真实环境中看似突发却判为平稳的输出。四、流量画像到告警策略的映射规则分类完成后按下述规则为各告警类型选择算法这也是 reliability_alert_policies.md 中Algorithm Selection Policy Mapping Process一节的延伸。4.1 Latency跟随流量画像Steady / Consistent → Long-Window Z-Score1 周回看基线脚本已验证至少 14 天历史因此可以安全使用 1 周基线。其原理是把当前 5 分钟 95 分位延迟与 1 周基线相减再除以 1 周内 5 分钟延迟序列的标准差通过子查询[1w:5m]计算 3时触发abs( histogram_quantile(0.95, sum(rate(workload_googleapis_com:gen_ai_invoke_agent_duration_bucket{monitored_resourcegeneric_node}[5m])) by (le, gen_ai_agent_name)) - histogram_quantile(0.95, sum(rate(workload_googleapis_com:gen_ai_invoke_agent_duration_bucket{monitored_resourcegeneric_node}[1w])) by (le, gen_ai_agent_name)) ) / stddev_over_time( (histogram_quantile(0.95, sum(rate(workload_googleapis_com:gen_ai_invoke_agent_duration_bucket{monitored_resourcegeneric_node}[5m])) by (le, gen_ai_agent_name)))[1w:5m] ) 3注意分母用子查询[1w:5m]计算 1 周内 5 分钟延迟的标准差分子直接用[1w]速率避免为均值再开一次子查询。Seasonal / Cyclical → Seasonal Decomposition1w 与 1d 平均基线将当前 5 分钟延迟与1 天前与 1 周前两个基线的均值比较比率 2触发。有两个硬性约束分子当前延迟绝不能带任何 offsetoffset 1d/offset 1w只能施加在分母以构造历史基线且该算法只应追踪尖峰方向不要同时追踪上升与下降否则 1 周后当异常点成为基线时会二次误报。Bursty / Inconsistent → Moving Averages1 小时基线5 分钟 95 分位延迟超过 1 小时均值 1.5 倍时触发用短窗口平滑掉短期抖动防止在尖峰场景下产生错误告警。4.2 Rapid Token Burn Rate同一套映射不同分组字段Cost 告警见 cost_alert_policies.md同样遵循上述四类算法但 PromQL 分组字段变为namespace对应generic_node资源且指标使用__name__形式引用含特殊字符的指标名workload_googleapis_com:gen_ai_client_token_usage_bucket。例如 Bursty 场景下的 Moving Averageshistogram_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])))4.3 Error Rate与画像无关的固定默认值无论脚本输出何种流量画像Error Rate错误率必须始终使用 Multi-Window Multi-Burn Rate SLO 告警或基于比率的静态阈值。原因在 reliability_alert_policies.md 中讲得很清楚错误率天然稀疏多为 0当标准差为 0 时 Z-Score 会出现除零导致的数学不稳定从而产生误报。因此错误率使用1 小时 5 分钟快燃与3 天 6 小时慢燃双窗口多燃烧率 SLO分别以(1 - slo_target) * 14.4和(1 - slo_target) * 1.0为阈值。这解释了主文档中Regardless of the scripts output profile这一硬性约束的底层动机。4.4 数据不足 / 无流量的降级回退以下两种情况必须回退到 no_historical_traffic_data.md 的用户询问流程脚本抛出ValueError提示数据点不足少于 14 天历史脚本输出New Agent / No TrafficAgent 处于非活跃状态。回退流程要求直接向用户询问预期的流量模式Steady/Consistent、Bursty/Inconsistent 或 Seasonal/Cyclical默认采用 Steady/ConsistentShort-Window Z-Score1 小时基线只需 1 小时历史即可激活若用户选择 Seasonal Decomposition需警告存在 1 周盲区因需要1woffset并建议先用 Short-Window Z-Score 或静态阈值作临时护栏。五、用户通知与确认流程在响应开头必须清晰沟通分析结果与选型决策共四个要点解释分类画像说明脚本输出的画像Seasonal / Cyclical、Steady / Consistent 或 Bursty / Inconsistent并引用脚本输出中的统计指标标准差、自相关、零值率若因零指标或数据不足回退到用户询问也需说明原因。提出映射方案给出对应的告警策略映射Latency 匹配流量画像Error Rate 使用 SLO Burn Rate。征询确认与定制询问用户该画像映射是否符合预期是否需要自定义标准差阈值。给出通俗解释用大白话说明每个告警测量的是什么、底层算法如何工作、触发意味着什么——这段解释应放在对话回复正文中而不是写进配置文件。六、Gotchas 与行为修正稀疏流量的预警主文档给出了一条关键的行为修正规则如果zero_ratio 0.95即使画像被判为 Steady / Consistent必须警告用户 Z-Score 告警可能不稳定建议改用 Short-Window Z-Score 或 Static Thresholds而不是 Long-Window Z-Score。这是因为高零值率意味着流量极度稀疏基于 1 周窗口计算出的均值/标准差统计基线缺乏代表性长窗口 Z-Score 的基线会被大量零值拉偏导致迟报或误报。配合该技能的完整流程还有几点值得一并注意详见 SKILL.md时长缓冲Duration Buffer短回看告警 25 小时如 Short-Window Z-Score、Moving Averages、Fast Burn SLO应设置duration 300s5 分钟缓冲过滤冷启动/部署抖动长回看告警 25 小时如 Long-Window Z-Score、Seasonal Decomposition、Slow Burn SLO平台禁用 duration需整体省略。动态基线盲区动态 Z-Score 基线会随系统数天缓慢劣化而自适应漂移对持续缓慢的错误视而不见建议并行配置一条硬静态阈值告警用于严格 SLA 执行。HCL 插值语法在 PromQL/SQL 字符串中引用 Terraform 变量必须使用${var.xxx}语法裸写var.xxx会在部署时失败。自纠错循环任何脚本含analyze_traffic.py异常退出时应阅读 stdout/stderr、分析错误、修正参数后重试再考虑升级或人工方案。七、验证与质量保障测试用例如何印证分类逻辑仓库提供了完整的单元测试 analyze_traffic_test.py它们直接印证了本文所述的分类行为可作为回归验证手段test_classify_steady/test_classify_seasonal/test_classify_bursty/test_classify_new_agent分别验证四类画像与对应推荐算法test_insufficient_data验证少于 4032 个点时抛出ValueErrortest_classify_constant_traffic常量流量判为 Steadytest_classify_near_zero_spike_falls_to_steady/test_classify_single_spike_bursty验证变异系数计算的边界均值阈值 0.0001test_main_live_query_request_count/test_main_live_query_token_usagemockMetricServiceClient验证实时查询主流程对两种指标类型分别产出 Steady 与 Bursty 结果test_align_to_grid验证稀疏时间点向固定 5 分钟网格的对齐逻辑。这些测试与 mock_traffic_data.py 中的STEADY_TRAFFIC、BURSTY_TRAFFIC、SEASONAL_TRAFFIC三组数据配合说明分类决策树在平稳-周期-突发三种形态上均有可复现的判定结果读者可据此在本地复跑验证需先按 1.2 节安装依赖。八、小结从数据到策略的完整链路当 Agent 拥有 14 天以上的历史指标时has_historical_traffic_data.md提供的是一条高度可操作化的链路安装依赖按目标策略确定--metric-type与--reasoning-engine-id延迟按gen_ai_agent_name、Token 按namespace以实时查询或指标文件模式运行analyze_traffic.py得到 zero-ratio、variance ratio、autocorrelation 与画像结论按决策表将画像映射为 Latency 算法Long-Window Z-Score / Seasonal Decomposition / Moving AveragesError Rate 固定走 Multi-Window Multi-Burn Rate SLO数据不足或无流量时回退到用户询问流程稀疏流量zero_ratio 0.95时降级建议使用短窗口或静态阈值在响应中完成画像解释、方案提出、用户确认与通俗说明四步沟通。这条链路确保了动态统计阈值算法的选型不是拍脑袋决定而是由 14 天真实流量数据的统计特征驱动并在源码与测试层面获得可验证、可复现的支撑。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考