Agent Observability · 起点

Agent 可观测性

一篇面向工程师的概念深读：把"可观测性"从"接个看板"和"给 agent 打分（eval）"里拆出来，讲清它作为把一次运行还原成 span 因果树的数据模型、机制、落地与选型。基于公开文档与论文，截至 2026-06；不含可运行代码进阶，重在建立可迁移的心智模型。阅读约半天。

时点：截至 2026-06 阅读：~半天 形态：概念为主（4 章 + 起点 + 自测） 代码：示意为主，未逐条本机运行

·适合谁

三条前置能力，缺一条会读得吃力：

前置知识

  • 搭过或正在搭一个会调用工具 / 检索的 agent——哪怕只是 demo；撞过"它答错了却没报错""这次怎么烧了这么多 token""线上慢在哪一步"这类问题。
  • 知道分布式追踪的 trace / span 大致是什么（读过 distributed-systems 更佳）。本篇就是把它套到非确定的 LLM 调用树上。
  • 用 Python 调过一次 LLM API，读得懂 JSON 结构的 span 数据。

·不适合谁

  • 完全没碰过 LLM 应用：先读 llm-api 与 prompt-engineering，再回来。
  • 想要的是"开发期怎么给 agent 打分、建回归集"：那是 eval，去 agent-eval。本篇第 1 章会把两者的边界讲死。
  • 想要 Reflexion / Self-RAG 那种"agent 自己边做边纠错"的运行期机制：去 agent-reasoning-patterns。它和本篇的"在线评估"是两回事，第 3 章会区分。
  • 只想要某个工具（LangSmith / Langfuse）的接入代码：直接看它官方 quickstart 更快；本篇讲的是背后的数据模型与取舍。

·读完之后你能做到什么

可观测性不是给 agent 接个看板，而是把一次非确定、多步的运行重建成一棵由 context propagation 造出来的 span 因果树——分清它和 eval / APM 的边界、看懂 token 与成本怎么逐 span 归因、知道哪些投产做法会在三个月后炸。具体可验证的能力：

  • 看到一段"怎么知道 agent 好不好 / 出没出问题"的讨论，立刻判断它说的是可观测性、eval、还是传统 APM，不再混为一谈。
  • 把一次 agent 运行读成一棵 trace，说出每个 span 装了什么、为什么 prompt / completion 放在 events 而不是 attributes。
  • 讲清那棵树怎么靠 context propagation 跨 LLM 调用 / 工具 / 多 agent / MCP 串起来；token 怎么上卷，成本为什么得厂商自己算。
  • 拿到一条失败 trace 沿父子链定位根因，而不是盲改 prompt；说得出生产该报警什么。
  • 在 10 个工具里按场景选型，避开已被取代的做法（手写日志、gen_ai.prompt、给新项目选 Helicone），并说清 2026 哪稳哪变。

一句话本质

日志记的是"发生了什么"；可观测性回答"为什么会这样"。对一个非确定、多步、会语义失败的 agent，那个"为什么"只能是一棵 trace（span 树）——靠 context propagation 把每一步的输入 / 输出 / token / 成本 / 延迟 / 错误，串成有父子因果的结构。

机制侧的硬核（全篇反复回扣）：trace 不是日志聚合，是一棵因果树；真正造出这棵树的是 context propagation（traceparent 把 parent_span_id 串过 reason→act→observe 循环、工具调用、多 agent 交接、乃至 MCP 边界）。没有它，面对 status 200 但答案是错的，工程师只能重启、加 print、盲改 prompt。

现状速览 · 截至 2026-06

已稳定（放心学）：trace / span 模型与每个 span 的 token / 延迟 / 成本捕获；OpenTelemetry 作为底座（gen_ai.* 属性前缀）；主流 SaaS 格局已定（LangSmith / Langfuse / Phoenix / Braintrust / Datadog）。

正在快速变化（带日期学）：OTel GenAI semantic conventions 仍是 "Development" 状态（即过去的 Experimental，属性名仍在变——v1.41 拆了 invoke_agent、加 reasoning / cache token；v1.38 弃用 gen_ai.prompt 改 input.messages）；OpenInference 与 OTel GenAI 两套约定并存、OpenLLMetry 捐给 OTel 卡了 14+ 个月；在线评估并入可观测性平台，eval 与 obs 边界融成 "LLMOps"；多 agent / session 级 trace 拓扑仍在标准化中。

已被取代（别当现状学）：print / 手写日志 → OTel 结构化 span；gen_ai.prompt / completion → input / output.messages；手写 callback → auto-instrumentation。Helicone 2026-03 被 Mintlify 收购转维护模式（学代理网关这个"模式"，别给新项目选这产品）；ClickHouse 2026-01 收购 Langfuse（$400M）。第 4 章逐条展开。

先打一支预防针 · 流畅感 ≠ 学会

这篇会刻意在每章末尾设自测与判别题。流畅地读完一段，和真正建立起判断力，是两回事。读的时候冒出这三句心里话，多半是错觉信号，不是掌握信号——

「我读得很顺」（熟悉，不等于学会）；「我做题很快」（多半题型眼熟）；「我没卡壳」（多半没真正碰到难点）。碰到自测题，先合上教程动笔，再对答案。

·概念地图

整篇挂在一条主线上：中心是可观测性的本质——把一次运行还原成一棵 span 因果树；四条实线是从这条主线展开的四个内容章；右下角那条虚线是容易混淆、但不是同一回事的 eval（你已有的 agent-eval），两者只在"在线评估"处交汇。

是什么 怎么造 用什么 做什么 ≠ 接缝 Agent 可观测性 一次运行 → span 因果树 ① 概念与边界 可观测性 ≠ eval ≠ APM ② 机制 trace 树怎么长出来 ④ 工具与前沿 选型 · 2026 走向 ③ 落地 调试·监控·在线评估 eval（你已有） 开发期·数据集·打分
图 0四个内容章都从中心那棵 span 因果树展开。注意：右下虚线框的 eval 和本篇都会"用模型看 agent"，但本篇在运行期还原单条真实运行、eval 在开发期对固定数据集打分——只在"在线评估"那条接缝相交，技术相通、目的与时机完全不同。

·怎么读：四条路径

按目的挑一条，不必从头匀速读到尾：

  • 只想厘清概念、不被 obs / eval 搞混（推荐）：第 1 章 → 第 3 章的"在线评估"一节 → 第 5 章自测的概念层。约 1.5 小时。
  • 要给自己的 agent 落地可观测性：第 1 章 → 第 2 章（机制）→ 第 3 章（调试 / 监控 / 陷阱）→ 第 4 章选型。
  • 做工具选型 / 带读别人的 trace：第 1 章（词汇）→ 第 4 章（工具横评）→ 回头补第 2 章机制。
  • 准备面试（"你怎么排查 agent 线上问题 / 控制 token 成本"是高频题）：全程通读 + 第 5 章应用判别题。

·目录

·学完之后

这篇建立的是"可观测性"的骨架，以下方向各自在它上面加一块：

  • eval（开发期打分）：本篇刻意划出去的另一半——回归数据集、LLM-as-judge、校准（agent-eval）。在线评估就是这两半的接缝。
  • Reflexion / 运行期自纠：agent 推理时自己评自己来纠错，和"对生产 trace 打分"是两回事（agent-reasoning-patterns）。
  • 多 Agent 可观测性：多个 agent 协作时的 trace 拓扑与归因——比单 agent 多一层"谁该负责"（multi-agent-patterns）。
  • 工具调用与 MCP：tool span 与 trace context 怎么过 MCP 边界（tool-use · mcp）。