Wiki Notes

Appearance

可观测性与 tracing 专题 ​

版本：v1.2

最后更新：2026-07-08

适用对象：正在做 LLM 应用、RAG、Agent、多工具工作流、审批系统和企业 AI 平台，需要定位质量退化、延迟波动、工具失败和成本异常的产品、平台与研发同学

AI 系统最难排查的地方，往往不是“接口报错了”，而是：

  • 请求技术上成功了，但业务上已经失败了
  • 同样输入，结果偶尔漂
  • 某一步突然变慢
  • 工具链偶发失败
  • 质量下降了，但接口仍然是 200

这正是为什么 AI 系统比传统 Web 接口更需要可观测性和 tracing。

因为传统系统很多问题可以靠：

  • 状态码
  • 异常日志
  • 单点性能指标

迅速定位；但 AI 系统经常需要回答的是：

  • 这次结果为什么不可信
  • 是哪一层退化了
  • 影响的是哪些用户和哪些任务
  • 能不能把这次失败转成后续评测材料

OpenTelemetry 当前 Observability primer、Traces、Instrumentation、Context propagation 文档，以及 OpenAI Agents SDK 当前 Tracing、Integrations and observability、Trace grading 等官方资料，在 2026-07-08 复核时都指向一个共同结论：

  • 可观测性不是为了多打一层日志，而是为了把一次 AI 任务还原成可解释、可比较、可回放的因果链。

1. 可观测性到底在解决什么 ​

OpenTelemetry 的基本分工很清楚：

  • traces 记录单次请求路径
  • metrics 记录趋势
  • logs 记录事件细节

翻译到 AI 系统里，本质上是在回答三类问题：

1.1 发生了什么 ​

  • 一次请求经过了哪些步骤
  • 每一步花了多久
  • 发生了哪些重试、回退、审批、打断、人工接管

1.2 为什么变差了 ​

  • 是模型退化
  • 是检索问题
  • 是工具失败
  • 是 prompt 变化
  • 还是输入分布变了

1.3 影响有多大 ​

  • 哪些用户受影响
  • 哪些场景受影响
  • 成本是否异常抬升
  • 是否需要灰度回滚

如果一个观测系统回答不了这三类问题，它大概率只是“日志堆放器”。

2. tracing 不是“多打一层日志” ​

很多团队说自己有 tracing，实际只是：

  • 把更多日志塞进同一个请求 ID

这不等于 tracing。

OpenTelemetry 对 distributed trace 的定义本质上是：

  • 由一次逻辑操作触发、跨多个组件传播的一组相关 span

换到 AI 场景里，更接近下面这条因果链：

text
user request
 -> retrieval
 -> rerank
 -> prompt assembly
 -> model call
 -> tool call
 -> second model call
 -> output validation
 -> final delivery

和“多几行日志”最大的区别在于：

  • 你能看到顺序
  • 你能看到父子关系
  • 你能看到耗时
  • 你能看到上下文如何跨服务传播

3. 为什么 AI 系统比传统接口更依赖 trace ​

3.1 问题常埋在中间步骤 ​

一次 RAG 问答出错，原因可能是：

  • 检索召回错了
  • metadata filter 错了
  • rerank 没把关键证据放上来
  • prompt 组装把上下文拼坏了
  • 模型偏离证据
  • 输出校验没挡住

如果只有最终输出日志，你几乎没法分层定位。

3.2 工作流天然跨组件 ​

一个企业 AI 请求常常会跨：

  • API 网关
  • 会话状态层
  • 检索服务
  • 向量库
  • LLM 服务
  • 工具服务
  • 审批服务
  • 事件总线

没有 trace 时，每个系统都可能“看起来没问题”，但用户体验已经崩了。

3.3 成本和延迟也必须看链路上下文 ​

真正有用的问题不是：

  • 今天贵了多少

而是：

  • 哪类请求贵了
  • 贵在 prompt 太长、reasoning 太重，还是工具重试太多

4. traces、metrics、logs 在 AI 系统里怎么分工 ​

4.1 traces 适合看单次链路 ​

更适合回答：

  • 这次为什么失败
  • 慢在哪一步
  • 哪个工具导致回退

4.2 metrics 适合看趋势 ​

更适合回答：

  • 本周 P95 延迟是否上升
  • 某类场景成功率是否下降
  • 哪个模型路由最近变贵了

4.3 logs 适合补细节 ​

更适合回答：

  • 某次审批为什么被拒
  • 某个工具的返回码是什么
  • 某次 schema 校验为什么失败

成熟系统不是三选一，而是：

  • trace 找个案
  • metrics 看趋势
  • logs 补背景

5. 对 Agent 来说，trace 是第一现场 ​

OpenAI Agents SDK 当前官方 tracing 文档明确说明：

  • SDK 内建 tracing
  • 会记录 model generations、tool calls、handoffs、guardrails 以及 custom events

这点非常关键，因为 Agent 工作流的复杂度通常体现在：

  • 路径长
  • 中间状态多
  • 失败点分散
  • 输出不止一个文本

所以对 Agent 来说，trace 不只是调试工具，它还是：

  • 工作流理解工具
  • 失败样例归因入口
  • 评测集采样入口
  • 发布回滚证据链

6. 一条好的 AI trace 应该怎样分层 ​

更实用的做法通常不是把所有事件平铺，而是分层建 span。

6.1 运行级 span ​

代表一次完整任务。

例如：

  • 一个用户请求
  • 一个语音会话 turn
  • 一个多 Agent 任务运行

6.2 阶段级 span ​

代表工作流里的主要步骤。

例如：

  • retrieval
  • rerank
  • model generation
  • tool execution
  • validation
  • approval wait

6.3 子操作 span ​

代表阶段里的关键细节。

例如：

  • 单次向量查询
  • 某个远端 API 调用
  • 某次 schema 校验
  • 某次 fallback 分支

如果没有这种层次，你最终会得到：

  • 要么太粗，定位不到问题
  • 要么太细，淹没在噪音里

7. AI 系统至少该埋哪些关键 span ​

结合 OpenTelemetry 的 instrumentation 思路和 AI 工作流实践，建议至少把下面这些节点埋成 span：

  • request receive
  • identity / tenant resolution
  • retrieval
  • rerank
  • context assembly
  • model generation
  • tool selection
  • tool execution
  • output validation
  • guardrail check
  • approval wait
  • final delivery

7.1 对多轮会话和语音系统，建议额外埋 ​

  • session start / end
  • turn detection
  • interruption
  • resume after approval
  • human handoff

7.2 对多 Agent 系统，建议额外埋 ​

  • handoff start / end
  • remote agent call
  • artifact creation
  • route decision

“埋哪些 span”最核心的原则不是越多越好，而是：

  • 凡是会影响质量、成本、时延、动作风险和治理决策的步骤，都应该能被单独观察

8. trace 字段不能只有技术信息，还要带业务上下文 ​

很多团队埋了 trace，但字段只有：

  • span name
  • duration
  • status

这通常不够。

AI 场景下，一条可用的 trace 至少建议包含四类字段。

8.1 请求与路由字段 ​

  • request id
  • session id
  • user / tenant
  • scenario
  • route / workflow
  • model

8.2 版本字段 ​

  • prompt version
  • workflow version
  • tool schema version
  • retrieval config version
  • evaluator version

8.3 成本与性能字段 ​

  • input tokens
  • output tokens
  • reasoning tokens
  • cache hit / miss
  • retries
  • fallback count
  • latency

8.4 风险与治理字段 ​

  • safety result
  • validation result
  • approval required / approved / rejected
  • sensitive data class
  • human handoff happened or not

没有这些字段时，你能看到“慢了”，却看不到：

  • 为什么这类租户总慢
  • 为什么这个新版本更贵
  • 为什么只有高风险场景退化

9. context propagation 是 trace 真能跨系统串起来的关键 ​

OpenTelemetry 当前 Context propagation 文档强调：

  • 分布式系统里的 trace 必须靠上下文传播把因果链串起来

这在 AI 系统里尤其重要，因为一次任务经常要跨：

  • API 网关
  • 检索服务
  • 模型服务
  • 工具服务
  • 审批服务
  • 事件处理器

如果上下文传播断了，结果通常是：

  • 每个服务内部都有 span
  • 但整条链拼不起来

9.1 AI 场景最常见的传播断点 ​

  • 异步任务队列
  • Webhook 回调
  • 事件总线
  • 工具服务跨语言调用
  • 审批后恢复执行

这些地方如果不额外处理，trace 常常会在关键节点断链。

10. 多轮状态和 trace 最好分开管理，但能互相引用 ​

很多团队会把历史状态和 trace 混成一个东西，这不太稳。

更实用的做法通常是：

  • 会话状态负责“运行要继续下去”
  • trace 负责“之后还能看懂发生了什么”

但它们要能互相引用，例如：

  • session id
  • previous response id
  • continuation id
  • approval id
  • handoff id

这样你既不会把 trace 当数据库，也不会在复盘时找不到状态上下文。

11. 对敏感数据要做分级，而不是默认全量记录 ​

OpenAI Agents SDK 当前 Running agents 和 tracing 相关资料里，trace_include_sensitive_data 被明确拿出来配置，这本身就在提醒一个现实：

  • tracing 不是默认越详细越好

企业场景里至少要先回答：

  1. 哪些输入输出可以记录原文
  2. 哪些只能记录摘要、哈希或脱敏版本
  3. 谁能访问 trace 平台

11.1 更常见的分级方式 ​

  • 低敏：可全量记录
  • 中敏：记录结构化摘要或裁剪片段
  • 高敏：只记元信息和判定结果，不记正文

11.2 最危险的做法 ​

  • 为了调试，把用户原文、检索证据、审批材料、工具参数、客户数据全部打进 trace 和日志

短期排查方便，长期很容易变成：

  • 权限事故
  • 合规事故
  • 内部滥用风险

12. 成本异常要能定位到“哪一段贵”，不是只看总账 ​

AI 系统里，成本监控最常见的误区是：

  • 只看一天花了多少钱

但更值得关注的是：

  • 是哪条链路贵了
  • 是哪个模型路由贵了
  • 是不是 prompt 变长了
  • 是不是 reasoning tokens 飙高了
  • 是不是重试次数上来了

更实用的成本观测通常会把下列字段挂到 trace 或 span 上：

  • 输入 token
  • 输出 token
  • reasoning token
  • cache 命中
  • 工具调用次数
  • 工具失败后重试次数

这样你才能从“今天超预算”继续追到：

  • 到底是哪一类任务在烧钱

13. tracing 最终要服务发布、灰度和回滚 ​

一个成熟的可观测性系统不只是帮你查事故，还应该支持：

  • 灰度比较
  • 版本对比
  • 快速回滚

13.1 发布时最值得对比的字段 ​

  • 新旧 prompt 版本成功率
  • 新旧模型成本差异
  • 新工作流是否引入更多 tool failure
  • guardrail 命中率是否异常变化
  • 高风险场景的人审比例是否变高

13.2 没有版本标签会怎样 ​

你只能看到：

  • 今天变差了

但看不到：

  • 是哪次发布导致的

所以 trace 与 metrics 至少要绑定：

  • model version
  • prompt version
  • tool version
  • workflow version

14. trace grading 能把“看 trace”升级成“用 trace 做评测” ​

OpenAI 当前 Trace grading 指南明确把 trace grading 定义为：

  • 对 agent trace 打结构化分数或标签

这件事特别值得重视，因为它把可观测性从“事后看图”推进到了“可重复评价”。

14.1 trace grading 适合评什么 ​

  • 工具调用是否正确
  • 决策路径是否合理
  • 是否进行了不必要的 handoff
  • 是否在证据不足时继续乱做
  • guardrail 触发是否合适

14.2 为什么这比只评最终答案更有价值 ​

因为很多系统的问题不是最终文本不好，而是：

  • 中间路径已经偏了

只看最终答案，你可能知道“结果不行”；看 trace grading，你更容易知道：

  • 是哪一步开始偏

15. 从线上 trace 到评测集，应该有一条明确闭环 ​

OpenAI 当前 Evaluation best practices 反复强调：

  • 要把开发和线上失败样本沉淀回 eval

对 AI 平台来说，更可执行的闭环通常是：

text
observe traces
 -> find bad runs
 -> bucket by failure mode
 -> extract reproducible cases
 -> add to eval dataset
 -> change prompt / workflow / tool / policy
 -> rerun eval
 -> watch production again

15.1 失败样本常见分桶方式 ​

  • 检索失败
  • 路由错误
  • 工具参数错误
  • 输出校验失败
  • 审批策略不当
  • 成本过高
  • 延迟过高

这条闭环真正重要的不是“有 dashboard”，而是：

  • 线上真实坏例子能持续转成离线可回归材料

16. 企业里更实用的建设顺序 ​

很多团队的观测系统做不起来，不是因为技术难，而是一开始目标过大。

更稳的顺序通常是：

16.1 第一阶段：先把请求链串起来 ​

至少能看到：

  • 请求进来了
  • 经过哪几步
  • 结果成功还是失败

16.2 第二阶段：补成本和版本维度 ​

至少能回答：

  • 哪类请求贵
  • 哪个版本开始变慢

16.3 第三阶段：补质量与风险维度 ​

至少能回答：

  • 哪类失败在增加
  • 哪类 guardrail 在频繁触发

16.4 第四阶段：接评测和告警 ​

至少能做到：

  • 自动发现异常
  • 自动抽取失败样本
  • 自动回流评测集

这个顺序的关键是：

  • 先保证能看到全链路，再追求更聪明的分析

17. 常见反模式 ​

  • 只有原始日志，没有真正的 trace 结构
  • 只有最终模型输出，没有中间步骤
  • 没有上下文传播，跨服务后 trace 断链
  • 没有 prompt / workflow / tool 版本标签
  • 成本异常时找不到是哪类请求导致
  • 只看技术错误，不看质量退化
  • 为了调试把敏感数据全量暴露
  • trace 和 eval 没有闭环

18. 推荐搭配阅读 ​

19. 重点官方资源 ​

以下资源在 2026-07-08 复核时可访问：

20. 落地检查清单 ​

  • 是否已经把请求、检索、模型、工具、审批、交付串成同一条 trace
  • 是否对关键节点设计了可独立观察的 span
  • 是否保证 trace context 能跨服务、异步任务和审批恢复传播
  • 是否为 trace 增加了 model / prompt / workflow / tool 版本标签
  • 是否记录了输入、输出、reasoning、重试、fallback 等成本字段
  • 是否对敏感数据做了分级采集，而不是默认全量记录
  • 是否能从 trace 快速定位是哪一层导致质量、时延或成本退化
  • 是否能把坏 trace 分桶、抽样并回流到 eval 集
  • 是否能支持灰度比较、发布回滚和事故复盘