《Agent 评测实战》21 | 可观测性与 Tracing：让每一步 Agent 行为可见

核心内容速览

• Trace = trial，Span = 动作：一次运行是一棵 span 树（LLM 调用/工具调用/检索/子 Agent 交接），带父子关系、输入输出、状态、成本——这是 transcript 的结构化、可下钻形式。
• tracing 支撑评测的三用途：下钻定位根因、组件级评分落地（trace-based evals：遍历 span 树逐环节打分）、生产轨迹回流成评测用例（飞轮燃料）。
• 监控→追踪→评测链：监控发现大盘异动 → tracing 下钻到坏 trace → 评测打分并固化用例。
• 用标准别自造：大栈统一遥测选 OpenTelemetry GenAI，LLM/RAG 深度调试选 OpenInference——可移植、可复用生态、面向未来。
• 分层采样策略：成功请求抽样 10%，失败/报错/护栏触发/超阈值 100% 全量采——平顺的少留，出事的一条不漏。
• 离线⇄线上公共底座：线上线下用同一套 trace 标准，失败 trace 才能无缝回流成评测用例。

适合谁 · 怎么用

先修：a19（Harness 拆解）。准备做组件级评测或线上监控的团队：先把 tracing 按标准接起来，它是后续一切下钻与回流的地基。与 a26（线上评测）连读。

闯关自测

先合上原文在心里作答，再点开对照。全对 = 本篇真正通关。

以下为原文全文

上方为本站原创导读，下方为原文完整收录，便于对照阅读。

上一讲，评测能跑起来了。但它现在还是个黑箱——一个 case 失败了，你只知道"分数低"，不知道到底是哪一步坏的。这一讲，我们给它装上眼睛：可观测性与 Tracing。

一句话说清这一讲的价值：

没有 tracing，评测只能告诉你"病了"；有了 tracing，你才能下钻到"病在哪一步"。

一、为什么 Agent 特别需要 tracing

传统软件监控看什么？成功率、延迟、错误码——看"最终结果"。这对单轮服务够用，但对 Agent 远远不够。

因为 Agent 是多步、长程、会调工具和子 Agent 的——一次运行内部，藏着一长串推理、调用、决策。传统监控只能告诉你"这次任务失败了"，可 Agent 的失败往往发生在第 7 步的某次工具调用、或某一步检索没召回、或推理链的中间跳了步——这些，看最终结果是根本看不见的。

tracing 干的事，就是把一次运行拆成一串可见的记录，让 Agent 内部那条原本黑箱的执行路径，变得透明、可查、可下钻。对 Agent 来说，tracing 不是锦上添花，是能不能定位问题的分水岭。

二、Trace 和 Span：两个基本概念

tracing 的世界里就两个核心概念：

• Trace（轨迹）：一次完整的 Agent 运行，对应一条 trial。
• Span（跨度）：运行里的一个动作——一次 LLM 调用、一次工具调用、一次检索、一步推理、一次子 Agent 交接。每个 span 带着：父子关系（谁调用了谁）、时间戳、输入输出、以及元数据（用了哪个工具、传了什么参数、花了多少 token、耗时多久、有没有报错）。

一次 Agent 运行，就是一棵由 span 组成的树。这正是 transcript 的结构化形式：transcript 是"记录"，而 trace 是"结构化、可查询、可下钻的记录"。评测 harness 里那个"轨迹采集器"，采的就是这棵 span 树。

一条退款 trace 大致长这样：

Trace: 退款请求 #1234 [失败] → llm.plan "先查订单状态" 120ms → tool.getorder args{id:#1234} → paid,未发货 80ms ✅ → llm.decide "满足条件，退款" 90ms → tool.refund args{id:#1234} → ERROR: GATEWAYTIMEOUT 30s ❌ → llm.respond "退款已处理"（← 没看错误！）110ms → tool.send_email "已成功退款" → ok 200ms。Outcome: order #1234 = paid（未退款）。

看这棵树，那条"谎报成功"的 bug 一眼就定位到了：tool.refund 那个 span 明明返回了 GATEWAY_TIMEOUT，可下一个 llm.respond 却无视它、直接说"已处理"。没有 trace，你只看到"这单没退成"；有了 trace，你精确知道是"退款超时 + Agent 没处理错误"。

一个 span 里该记什么？给你一份最小清单，每个 span 至少带上：

• 类型：这步是 LLM 调用 / 工具调用 / 检索 / 子 Agent 交接？
• 输入 / 输出：收到什么、产出什么（工具的参数与返回、LLM 的 prompt 与 completion）。
• 状态：成功 / 失败 / 错误信息。
• 成本与耗时：token 数、金额、延迟。
• 父子关系：属于哪条 trace、由哪一步触发。

记全了，你才能既下钻定位（靠输入输出和状态）、又做非功能评测（靠成本耗时）。记漏了中间步骤，等于给自己留了盲区。

三、Tracing 怎么支撑评测：三个用途

tracing 不只是调试工具，它是评测体系的地基材料。三个用途：

用途一：下钻定位。一个失败分数 → 调出这条 trace → 看是哪个 span 坏的：工具返回了错误？检索没召回？推理跳了步？这就是把"端到端失败"下钻到"组件级根因"的操作，而 trace 是唯一的下钻依据。

用途二：组件级评分的落地。"工具调用评测"、"单步检索质量"——这些组件级的评测，靠的就是能拿到单个 span。有了结构化的 trace，你才能对"某一次工具调用的参数"、"某一步检索的召回"分别打分，而不是只能评最终答案。这种"直接给 trace 里的 span 打分"的做法，业界叫 trace-based evals（基于轨迹的评测）：评分器不只看最终 output，而是遍历 span 树，对每个感兴趣的环节各打一分。反过来说，你的 trace 记得多细，你能做的组件级评测就有多细；trace 是天花板。

用途三：生产轨迹回流成评测用例。线上的 trace，就是现成的真实用例。把线上失败的 trace 捞出来、固化成评测集里的新 task——这就是"评测集生长飞轮"的燃料来源。production traces become datasets（生产轨迹变成数据集），是这个飞轮转起来的关键。

从一条 trace，到一片监控

单条 trace 让你看清"这一次"发生了什么；但要看"整体健康度"，你得把成千上万条 trace 聚合起来。（顺带正名：传统可观测性的"三支柱"指 Metrics / Logs / Traces；这里借"三层"说法，讲 Agent 评测里层层递进的三件事——）

• 监控（Monitoring）：聚合指标看大盘——成功率、平均延迟、成本、幻觉率随时间的曲线。回答"整体好不好、有没有变差"。
• 追踪（Tracing）：单条运行的 span 树。回答"这一次为什么坏"。
• 评测（Evaluation）：对 trace（或其中的 span）打分，把"行为"变成"质量分数"。回答"它做得对不对"。

三者的关系是一条链：监控发现大盘异动 → 追踪下钻到具体的坏 trace → 评测给这些 trace 打分、并把典型失败固化成用例。tracing 是中间那根轴——没有它，监控只是一堆没有细节的数字，评测也无从定位。

四、别自己发明格式：用 tracing 标准

很多团队一开始自己打日志记轨迹，格式五花八门。问题是：换个可观测平台、换个 Agent 框架，就得重写一遍采集和解析。现在这件事有标准了，直接用，别重复造轮子。两个主流标准：

OpenTelemetry GenAI semantic conventions。由 OpenTelemetry 的 GenAI SIG 制定，是一套标准化的 span 属性名、指标名、事件 schema——统一了 LLM 调用、agent 步骤、向量检索、token 用量、成本等的命名。它最大的价值是统一词汇：一个 LangChain agent 产生的 span，和一个裸 OpenAI 调用产生的 span，长得一模一样。适合"要在一个包含大量非 LLM 服务的大技术栈里统一遥测"的团队。

OpenInference（Arize/Phoenix）。更偏 LLM 专用的深度——完整捕获 prompt/completion、把检索作为一等公民的 span、更细粒度的 span 类型，并对 LangChain、LlamaIndex、CrewAI 等广泛自动埋点。适合"RAG 重、要马上能调试 LLM 细节"的生产 Agent。

怎么选？一句话：大栈统一遥测 → OpenTelemetry GenAI；要 LLM/RAG 的深度调试 → OpenInference。很多可观测平台两者都支持，你也不必二选一到底。

为什么一定要用标准而不是自己编？三个理由：可移植（换平台/框架不用重写采集）、可复用生态（现成的可视化、告警、分析都认这套格式）、面向未来（标准在演进，你搭个私有格式迟早要还技术债）。这就是这一讲要你记住的一个具体决策：tracing 从第一天起就按标准来。

五、Tracing 是离线与线上的公共底座

tracing 有个特别重要的角色——它同时服务离线评测和线上监控，是连接两者的公共语言：

• 离线：评测 harness 的轨迹采集器，按标准记 trace。
• 线上：生产环境也接同一套 trace 标准。

于是，线下评测和线上监控用的是同一种"语言"看 Agent——同样的 span 结构、同样的属性。这带来一个巨大的好处：线上发现的失败 trace，可以无缝地回流成线下的评测用例，因为它们本就是同一种格式。反之，如果线上线下各记各的格式，这个回流就处处是转换和摩擦。

记住这个定位：tracing 不只是调试工具，它是打通"离线评测 ⇄ 线上监控"的那个公共底座。

怎么从零接入

落地路径其实很短，三步：

1. 埋点（instrument）：把 Agent 里每个关键动作包成 span。好消息是大多数框架（LangChain、LlamaIndex 等）有现成的自动埋点，接一下就有 trace，不必手写。
2. 导出（export）：按标准（OTel / OpenInference）把 trace 异步导出到后端。
3. 接平台：送进一个可观测平台（LangSmith、Langfuse、Phoenix、Braintrust……）做存储、可视化、告警，以及在上面直接跑评测。

从 MVP 角度，第一版哪怕只把"工具调用"和"最终输出"两类 span 记全，就已经能解决大半的定位难题——先接起来，再逐步记细。

六、几个实务细节

• 采全，别只采最终输出：中间 span 才是定位的关键。宁可多采，别漏采中间步骤。
• 隐私与脱敏：trace 里会带用户数据（prompt、检索内容），要做脱敏和访问权限控制——尤其线上流量。
• 采样策略：全量记 trace 成本不低，得分层采。一个实用的线上采样策略是——成功的请求按比例抽样（比如 10%）留个大盘样本，而失败、报错、护栏触发、延迟/成本超阈值的请求 100% 全量采（它们才是你最需要看的）。换句话说：平顺的少留几条够统计就行，出事的一条都不能漏。
• 别让 tracing 拖垮性能：trace 的导出要异步、批量，别在关键路径上同步阻塞 Agent。
• 命名保持一致：span 的类型名、属性名要统一——否则你想按"所有 refund 工具调用"聚合分析时，会发现它们被记成了五花八门的名字，根本聚不起来。

这些和"评分器也是代码"是一个道理——tracing 基础设施本身也要被认真对待，它记漏了、记错了，你后面所有的下钻和组件级评测都是空中楼阁。

小结

• 为什么需要：Agent 多步、长程，传统"看最终结果"的监控看不见内部；tracing 把一次运行拆成可见的 span 树。
• Trace / Span：一次运行是 trace（=trial），每个动作是 span——是 transcript 的结构化、可下钻形式。
• 三个用途：下钻定位根因、支撑组件级评分（trace-based evals）、生产轨迹回流成评测用例。
• 用标准别自造：OpenTelemetry GenAI（大栈统一）vs OpenInference（LLM/RAG 深度调试）。
• 公共底座：tracing 用同一种语言打通离线评测与线上监控。
• 实务：采全、脱敏、失败全量采、异步导出。

思考题

1. 你现在排查一个 Agent 失败，靠的是翻日志、还是能调出一条结构化的 trace 一眼看到哪一步坏了？如果是前者，你大概率在"组件级下钻"上很吃力。
2. 你的轨迹是自己编的格式，还是用了 OTel GenAI / OpenInference 标准？如果是自编的，想想换平台或框架时的迁移成本。
3. 你的线上和线下，用的是同一套 trace 格式吗？如果不是，"线上失败回流成线下用例"这条飞轮，是不是转得很费劲？