05. 可观测性、Tracing与 Trace Grading

版本：v1.1

最后更新：2026-07-08

适用对象：已经有日志和监控，但仍然很难解释“这次到底是 Prompt、模型、检索、工具还是审批出了问题”的团队

很多团队在 AI 系统里也会说“我们已经有可观测性了”，但真到线上质量波动时，还是只能回答：

• 最近好像变差了
• 某些请求好像更贵了
• 某些工具调用好像更容易失败了

却很难回答：

• 到底是哪一步开始偏了

按 2026-07-08 可访问的 OpenAI Agents SDK、Integrations and observability、Evaluate agent workflows、Trace grading、Results and state 官方资料来看，更有生产价值的做法通常不是“只补更多日志”，而是：

• 先把一条请求拆成完整 trace
• 再把 trace 绑定版本、门禁和事故复盘

1. 先别把“日志”和“Tracing”混成一件事

1.1 普通日志更像事件碎片

它通常会告诉你：

• 收到请求了
• 调了模型了
• 工具报错了
• 返回给用户了

这对排障有用，但经常缺少：

• 因果关系
• 上下文边界
• 一整次运行的层级结构

1.2 Tracing 更像一整次运行的骨架

OpenAI Trace grading 直接把 trace 描述成一条 run 的端到端记录，本身就说明 trace 关注的不是单条日志，而是：

• 模型调用
• 工具调用
• handoff
• guardrail
• 审批 / 中断
• 最终结果

怎么在一次运行里串起来。

1.3 为什么这一步很关键

因为 AI 系统里的问题往往不是单点错误，而是链路偏移：

• Prompt 改了，导致工具选择变了。
• 检索结果变了，导致引用变差了。
• 审批策略变了，导致本来可自动完成的任务被大量挂起。
• 模型换了，导致同样输入的轨迹变长了。

如果没有 trace，这些问题很容易被误判成“模型最近不稳定”。

1.4 Tracing 也不等于“再加一套监控”

OpenTelemetry 当前官方文档把 trace 定义成由多个 spans 组成的完整分布式操作记录；OpenAI 当前 Integrations and observability 则明确说明 Agents SDK 默认就能把一条 run 里的 model calls、tool calls、handoffs、guardrails 和 custom spans 串起来。

把这两类官方资料放在一起看，更容易形成一个稳定心智：

• 指标更像“温度计”
• 日志更像“零散事件”
• trace 更像“带父子关系的运行骨架”

所以真正成熟的 AI 可观测性，通常不是：

• 指标一套
• 日志一套
• trace 再单独一套

而是让三者分别回答不同问题：

• 指标回答“哪里在波动”
• 日志回答“发生过哪些事件”
• trace 回答“这条请求到底怎么走到这里”

2. 生产里的 AI 可观测性至少要分五层

2.1 请求层

最基础的是：

• 请求 ID
• 用户 / 租户
• 功能入口
• 版本号
• 是否命中灰度

2.2 模型层

重点看：

• 用了哪个模型
• 哪个 Prompt 版本
• 输入输出 token
• 推理耗时
• structured output 是否成功

2.3 检索与工具层

重点看：

• 检索了什么
• 命中了哪些来源
• 调了哪些工具
• 工具参数是什么
• 工具返回值是什么

2.4 审批与运行层

重点看：

• guardrail 是否触发
• run 是否暂停
• 人工 review 卡在了哪里
• 长任务状态是否恢复

2.5 业务结果层

重点看：

• 用户任务是否完成
• 工单是否关闭
• 文档是否抽取成功
• Agent 是否实际执行到了预期动作

2.6 状态与中断层

OpenAI 当前 Results and state 官方资料明确强调：

• result 不只是 final output
• 它还包含 handoff boundary
• next-turn continuation surface
• paused-for-review 时可恢复的 snapshot

这意味着真实生产里的 trace，不能只看“这一步调用了什么”，还要看：

• run 在哪一步暂停
• 是因为 guardrail、human review，还是工具等待
• 恢复时沿用的是哪份上下文和状态
• 中断前后的负责人是不是变了

对 Agent / 工作流系统来说，这一层非常关键，因为很多线上问题不是：

• 调用失败了

而是：

• run 卡住了
• review 没恢复
• 恢复后沿用了错误状态

2.7 安全与治理层

很多团队把安全日志单独放到别的系统里，但生产诊断里它依然应该和 trace 能对上。

至少建议让 trace 能关联到：

• guardrail 版本
• approval / review id
• policy id
• 是否命中风险路由
• 是否触发人工接管

否则到了事故现场，很容易出现：

• trace 里看得见工具被调了
• 但看不见为什么会放行

3. 更实用的 trace，不是“采得越多越好”

3.1 真正有用的是能复原决策链

一个更有价值的 trace，通常至少能回答：

1. 这次请求走了哪条路由。
2. 模型在关键节点拿到了什么上下文。
3. 工具为什么在那个时机被调起。
4. 审批、guardrail 或中断在哪里生效。
5. 最终结果为什么会成功或失败。

3.2 不是所有内容都该原样留存

AI trace 里很容易包含：

• 用户敏感信息
• 检索原文
• 工具返回的业务数据
• 审批上下文

所以实际落地时通常要分层：

• 排障字段
• 审计字段
• 脱敏后的评测字段

3.3 追求“全量明文记录”通常不是稳态

更稳的做法通常是：

• 对高价值链路保留关键证据
• 对敏感负载做脱敏或摘要
• 对全量原文设置更短留存期

3.4 trace 结构最好和 run 结构、span 结构一一对应

OpenTelemetry 当前官方资料把 span 视为 trace 的基本工作单元；OpenAI 当前 Integrations and observability 也明确支持 custom spans。

对 AI 系统来说，一个更稳的结构通常类似：

trace
└─ run / workflow
   ├─ routing span
   ├─ retrieval span
   ├─ model call span
   ├─ tool call span
   ├─ approval / guardrail span
   └─ finalization span

这种结构的价值在于：

• 你能看见一整次请求的父子关系
• 你能单独比较 retrieval、tool、approval 哪段最不稳
• 你能把 custom spans 加在真正重要的业务节点上

如果 trace 只有一个大平铺列表，后面想做：

• 轨迹对比
• 阶段耗时
• 失败定位
• 发布基线

都会很吃力。

3.5 采样策略、保留期和回放等级最好一开始就分层

很多团队一上 trace 就有两个极端：

• 全量留明文，成本和风险迅速爆炸
• 只留极少字段，出事故时又什么都回放不出来

更稳的分层通常是：

• 核心业务 / 高风险动作：高保真 trace，保留关键证据
• 普通在线流量：摘要化 trace，保留结构与指标
• 调试 / 试验流量：更高采样，但更短保留期
• 事故样本池：单独冻结，禁止被常规 TTL 提前清走

真正要治理的不只是“采不采”，而是：

• 哪些样本值得高保真
• 哪些样本只保结构化摘要
• 哪些样本必须进入事故和评测资产池

4. 为什么要先做 trace，再做大规模 eval

OpenAI Evaluate agent workflows 当前明确强调：

• 还在调行为时，先从 traces 开始
• trace grading 是发现 workflow 级问题最快的方法

这背后的工程含义很直接：

• 如果你还不知道系统到底在哪一步出错
• 先上大规模回归集，很多时候只会看到“分数下降了”

却不知道该修哪里。

4.1 Trace 更适合早期排查

因为它回答的是：

• 这次 run 到底发生了什么

4.2 Evals 更适合稳定比较

因为它回答的是：

• 这版相对上一版变好还是变差

4.3 两者更稳的组合方式

1. 先用 trace 找故障模式。
2. 把故障模式沉淀成 eval 样例。
3. 再把这些样例接进发布门禁。

4.4 trace 分桶是从“看个案”走向“看模式”的关键一步

当线上样本规模起来后，团队真正需要的通常不是：

• 单独看十几条坏 case

而是先把 traces 按模式分桶，例如：

• 工具选错桶
• 检索证据脏桶
• 审批卡住桶
• 轨迹过长桶
• handoff 丢上下文桶
• 成本异常桶

这一步很重要，因为：

• 个案只能解释“发生了什么”
• 分桶才能回答“最近最常发生哪一类问题”

也只有分桶后，trace grading、eval、发布门禁和事故 runbook 才容易真正串起来。

5. Trace grading 真正解决什么问题

OpenAI Trace grading 当前强调的不是只给最终答案打分，而是给整条轨迹打结构化标签。

5.1 它比“最终答案对不对”更有价值的地方

很多系统最终答案错了，真正根因却不同：

• 选错工具
• 检索证据脏
• 审批绕路
• handoff 时上下文丢失

5.2 Trace grading 更适合回答的问题

• 工具选择是否合理
• 是否绕过了应有审批
• 轨迹是否过长
• 哪个步骤最常导致失败
• 哪类失败是模型问题，哪类是编排问题

5.3 这一步为什么特别适合 Agent / 工作流系统

因为 Agent 问题往往不是“答错一句话”，而是：

• 路线走偏了
• 选错动作了
• 该停没停
• 该交给人没交

5.4 一套可落地的 trace grading 标签通常不止“好 / 坏”

更实用的标签体系通常至少分三层：

1. 结果层
   • 成功 / 失败 / 部分成功 / 需要人工接管
2. 路径层
   • 工具选择合理 / 检索合理 / handoff 合理 / 审批合理
3. 资源层
   • 成本过高 / 轨迹过长 / 延迟异常 / 缓存未命中

如果只保留：

• 最终 pass / fail

后面很难回答：

• 失败是因为路径错了，还是资源模型不合理
• 通过的 case 是否其实已经过贵或过慢

所以更成熟的 trace grading 通常更像：

• 结构化诊断标签

而不是一颗总分。

6. 生产里最值得先绑定到 trace 的字段

6.1 版本字段

至少建议绑定：

• 模型版本
• Prompt 版本
• tool schema 版本
• retrieval / rerank 配置版本
• 审批策略版本

6.2 成本与性能字段

至少建议绑定：

• input / output token
• cached token
• 单步耗时
• 端到端耗时
• 工具等待耗时

6.3 质量字段

至少建议绑定：

• eval bucket
• trace grade
• 人工 review 结果
• 最终任务完成状态

6.4 运营字段

至少建议绑定：

• 是否灰度流量
• 是否回滚前后版本
• 是否人工接管
• 是否进入事故样本池

6.5 状态与恢复字段

OpenAI Results and state 当前把 pause、history、resumable snapshot 都放在同一条 result surface 语义里，这意味着 trace 里至少还值得补：

• run / conversation id
• interruption reason
• last active agent
• resumed from which checkpoint
• review decision
• snapshot version

这些字段很关键，因为长工作流最难查的往往不是“哪次调用报错”，而是：

• 为什么暂停后没有恢复
• 为什么恢复后上下文变了
• 为什么切给下一个 agent 以后 owner 变了

6.6 关联键字段

为了让 trace 能和别的系统真正打通，通常还需要稳定关联键：

• trace id / span id
• release bundle id
• eval run id
• incident id
• dataset bucket
• tenant / workspace id

没有这些键值时，常见问题就是：

• 监控平台看到异常
• 评测平台看到降分
• 值班同学也知道刚发布过

但三边数据根本串不起来。

7. Tracing 不只是 debug，也应该进发布流

很多团队会记录：

• 本次改了 Prompt
• 本次换了模型

但不会把对应 trace 样本一起挂上发布记录。

结果就是：

• 能看到版本变了
• 但看不到轨迹变成什么样了

更稳的发布动作通常包括：

1. 发布前先跑关键样例。
2. 对关键样例保留基线 trace。
3. 新旧版本做 trace 对比。
4. 失败样例直接回流 eval 集或事故池。

7.1 一个更像生产系统的 release evidence bundle 会包含什么

很多团队会保留：

• commit id
• 配置 diff

但不会把“为什么敢发”留成证据。

更稳的 release evidence bundle 通常可以同时挂上：

• 关键样例集结果
• 代表性 baseline traces
• trace grading 汇总
• 关键指标对比：成本、时延、成功率、人工接管率
• 发布范围：全量 / 灰度 / 特定租户
• 回滚入口和回滚条件

这样后面出现问题时，团队不仅知道：

• 发了什么

还能知道：

• 发之前看到的运行证据是什么

8. 事故复盘为什么离不开 trace

很多 AI 事故表面看像一个结果问题，但真正复盘时要追：

• 这个答案是怎么来的
• 哪个工具返回了错误证据
• 审批为什么没拦住
• 用户在哪个节点被错误引导

没有 trace 的复盘通常只剩猜。

更实用的做法通常是：

• 把事故 trace 打标签
• 把事故模式变成 trace grading 规则
• 把高风险样本加进回归集

8.1 事故 trace 最好直接沉淀成“可反复运行的证据包”

一个更实用的事故证据包通常至少包括：

• 原始触发输入摘要
• 对应 trace 链接
• retrieval / tool / approval 关键 spans
• 版本、策略、模型、prompt 绑定信息
• 事故标签与影响范围
• 修复后回放结果
• 对应新增的 eval / trace grading 规则

这样事故复盘就不只是写一篇文档，而是把：

• 证据
• 回放
• 规则
• 门禁

一起固化下来。

9. 最容易踩的坑

• 只看 API 监控，不看 end-to-end trace。
• 只留最终回答，不留中间检索和工具证据。
• 只在本地调试时看 trace，上线后不接发布和门禁。
• 把 trace 当成全量原文仓库，不做分层留存和脱敏。
• 只给最终答案打分，不给轨迹打结构化标签。
• 没有 custom spans，导致业务关键节点都挤在“模型调用”这一层里。
• 没有 interruption / resume 字段，长工作流一旦卡住就很难查。
• 只有 trace，没有能落到 incident / eval / release 的稳定关联键。
• 只做单条 trace 浏览，不做失败模式分桶。

10. 推荐搭配阅读

• 03-评测门禁、回放与版本基线
• 06-缓存、Batch、Flex与后台任务编排
• 可观测性与tracing专题
• AI治理与审计专题
• 评测运营与案例

11. 重点官方资源

以下入口在 2026-07-08 检查时可访问：

• OpenAI Agents SDK
• OpenAI Integrations and observability
• OpenAI Evaluate agent workflows
• OpenAI Trace grading
• OpenAI Results and state
• OpenAI Production best practices
• OpenTelemetry Traces
• OpenTelemetry Semantic Conventions
• OpenTelemetry GenAI semantic attributes registry

12. 什么时候该跳到别的目录

• 当你开始治理批处理、后台任务和缓存分层时，跳到 06-缓存、Batch、Flex与后台任务编排。
• 当你开始建设更细的样例运营、告警和失败回流时，跳到 评测运营与案例。
• 当你开始治理日志权限、审计字段和敏感留存时，跳到 安全治理。