升级 ADK 后，旧的 call_llm 看板为何失灵

Google ADK Python 2.13.0 将默认遥测切换到 OpenTelemetry GenAI v2 语义约定，旧的 call_llm span 不再按原方式产生；这会让依赖旧 span 名称或 gcp.vertex.agent.* 属性的采集规则、告警和仪表盘失去数据。升级不是只改依赖版本：需要把下游查询迁移到新语义，并在兼容窗口内决定是否暂时通过环境变量保留旧 schema。

2.13.0 改变的是遥测默认值

ADK 2.13.0 的官方发布说明把 telemetry 列为破坏性变更：默认采用 OpenTelemetry GenAI v2（发布说明写作 otel_semconv_1_44），移除 call_llm；如需继续使用旧的 v1 schema，可设置 ADK_TELEMETRY_SCHEMA_VERSION_OPT_IN=otel_semconv_1_36。因此，受影响的不是模型调用协议，也不是 Agent 的工具执行逻辑，而是运行记录的形状、span 名称及消费者对这些字段的假设。

此前 ADK 自有的 call_llm span 使用 gcp.vertex.agent.* 属性。升级之后，消费端如果仍以 span 名称筛选模型调用、从旧属性提取输入输出 Token 或将 call_llm 作为仪表盘的主查询条件，数据可能表现为曲线中断、面板空白或告警不再触发。日志后端仍在正常接收遥测，并不代表旧查询仍然适用；应先核对新 span 与属性，而不是仅凭“没有错误”判定迁移完成。

这项版本变化也不意味着所有遥测字段都已经稳定。ADK 将其描述为 GenAI v2 语义，而 OpenTelemetry 的 GenAI span 文档将相关约定标记为 Development。团队应把语义约定版本视为可演进接口：记录 ADK 版本、采用的 schema 版本和导出配置，并在升级时跑一次遥测契约检查。

先盘点哪些下游依赖旧 schema

迁移前，先在采集器、查询仓库和告警配置中搜索 call_llm、gcp.vertex.agent. 以及旧版输入输出字段名。不要只查仪表盘：转换处理器、采样规则、数据脱敏、成本归因脚本和告警条件都可能把旧 span 名称写死。把命中项整理为清单，并标记每一项的拥有者和验证方法，避免只修了可视化却漏掉后台处理链路。

随后在与生产相同的依赖锁定和导出配置下运行一个最小 Agent：至少触发一次模型调用和一次工具调用，把导出的 trace、日志或测试导出器结果保存为样本。用样本确认新版本实际输出的 span 名称、gen_ai.* 字段和错误状态。不要根据字段名称自行猜测映射；语义约定会区分请求模型、响应模型、Provider 和操作名称，错误字段也应使用相应错误语义。

在测试环境并行执行旧查询和新查询，观察一个完整的业务周期。检查维度是否仍能按模型、操作和错误类型聚合，Token 用量是否来自新事件或 span 中实际存在的属性；若某一字段没有输出，应明确记录为不可用，而不是用旧字段值或估算补齐。测试应覆盖成功、工具调用和失败路径，因为只验证一次成功请求无法证明异常告警和工具链路仍有效。

用兼容开关安排迁移窗口

发布说明给出的回退方式是设置 ADK_TELEMETRY_SCHEMA_VERSION_OPT_IN=otel_semconv_1_36，以继续使用旧 schema。它适合作为受控迁移窗口的兼容选项，不宜变成未记录的长期默认：如果生产暂时依赖 call_llm，把开关写进部署配置与运行手册，标记移除日期，并在预发布环境验证升级后的默认路径。

建议把升级拆成两个可回滚的变更。第一步部署能够同时识别新旧格式的采集与查询逻辑，且不改变 ADK 版本；第二步再升级到 2.13.0，验证新格式进入后端并且旧开关按预期工作。若平台无法同时查询两套数据，至少保留旧配置快照、导出样本和回退步骤。回滚时应一起回滚 SDK 与 schema 选择，避免 SDK 已回到旧版但遥测仍按另一套语义解释。

切换完成后，移除兼容开关，并更新仪表盘说明、告警阈值和遥测数据字典。仪表盘标注“ADK 2.13.0+”或 schema 版本，有助于区分真实业务流量变化和采集格式变化。排查 Agent 行为时，也可结合 ADK 中止执行与工具调用收尾对照运行时事件；若正在更换模型入口，则在模型与平台目录核对实际接入对象，但不要把 API 调用成功当成遥测迁移成功。

内容捕获与 schema 是两个不同开关

迁移 span 名称之外，还应复核提示词和模型回复是否会被写入遥测。ADK 的 2.13.0 遥测配置指南说明，旧版 ADK span 中的内容捕获与 GenAI 语义约定路径有不同控制方式；TelemetryConfig 的内容捕获模式可以区分完全不捕获、只写事件、只写 span 或两者都写。环境变量 ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS 也影响旧 span，但它不等价于统一关闭所有内容路径。

因此，保留旧 schema 的决定不能代替隐私审查，切换新 schema 也不能自动证明敏感内容没有导出。需要逐一检查导出目标、日志与 span 的内容开关、访问控制和保留策略，并使用可识别的测试文本确认它是否出现在导出数据里。生产验证应采用合成提示词，不要拿真实用户会话做脱敏测试。

升级验收应验证数据契约

可将以下检查放进升级验收：锁定并记录 ADK 的确切版本；确认生产最终使用的 schema 版本；用固定请求生成模型调用、工具调用和错误样本；验证采集器能解析新语义并正确关联 Trace；检查关键告警在新字段下仍可触发；最后检查内容捕获策略与导出端一致。若迁移过程中必须保留旧 schema，应把兼容变量、责任人和退出条件纳入变更记录。

OpenTelemetry GenAI 约定仍处于 Development 状态，这意味着后续变化不能只靠静态字段映射承受。更稳妥的做法是在升级测试中保存脱敏后的遥测样本，并对 span 名称、必需属性和核心聚合维度做契约断言。这样一来，未来升级若再次改变默认值，可以在进入生产之前发现，而不必等到看板空白或告警沉默后才追查。