Agent trace 与可观测性

Agent 开发进阶考 14 题讲解 4 段

一条 trace 是一棵 span 树：每次模型调用、每次工具调用各一个 span，带上 OTel 的 gen_ai.* 语义约定字段，才能重放、归因成本、定位是哪一步错的。内容捕获与采样策略要权衡隐私与排障需要，线上监控看的是分布与漂移。

也叫：trace · 可观测性 · OTel · OpenTelemetry · span · 重放 · gen_ai

先学ReAct 循环与退出条件

再学trace 字段与 OTel 语义约定

一条 trace 长什么样出自 T3-11

原文示意

trace_id: 7f3a...                                    总耗时 8.4s / 12,430 tokens
│
├─ span: invoke_agent  (name=data_query_agent)       8.4s
│  │
│  ├─ span: chat  (model=..., input=3,200 tok, output=180 tok)      1.2s
│  │     └ 决策：调用 list_tables
│  ├─ span: execute_tool  (name=list_tables)                        0.3s
│  │     └ 返回 47 张表名（1,100 tok）
│  ├─ span: chat  (input=4,600 tok, output=210 tok)                 1.5s
│  ├─ span: execute_tool  (name=run_sql, args={...})   ← ERROR      0.8s
│  │     └ 错误：column "return_date" does not exist
│  ├─ span: chat  (input=5,300 tok, ...)                            1.4s
│  └─ span: execute_tool  (name=run_sql, args={...})   ← OK         2.9s
│
└─ 事件：context_compaction  (before=48k, after=12k)   ←  必须记录为事件

截至 2026-08，这套结构已经有了事实标准：OpenTelemetry 的 GenAI 语义约定（由 CNCF 下的 GenAI SIG 维护）定义了 gen_ai.* 属性族，以及 agent / workflow / tool / model 等 span 类型和必需的耗时、token 用量指标，invoke_agent → chat → execute_tool 的嵌套关系是其中的核心形状。

三条实用信息：

状态：这套约定的多数部分仍标注为实验性/发展中，schema 可能变化，但span 与属性的形状值得现在就采用——它让你的 trace 能被任何支持 OTLP 的后端读懂，也能和已有的服务 trace 拼在一张图上。
内容捕获默认关闭：出于 PII 顾虑，prompt/response 正文默认不进遥测。你要单独决定采样策略和脱敏方案。
生态：主流可观测/评测平台（LangSmith、Arize Phoenix、Langfuse、W&B Weave 等，其中 Phoenix 与 Langfuse 开源）都在向这套约定靠拢；部分编码 Agent 已直接以该约定发射遥测。另有 OpenInference 等并行标准。

以上节选自T3-11 Agent 评测与 trace——它们会以"看起来成功"的方式失败，读全文能看到前后语境。