概念与边界：可观测性、eval、APM 三者别再搞混

大多数 SDK 文档的描述是："接入之后你就有 trace 了。"这句话没错，但它跳过了三个真正重要的问题：那棵树由哪些字段构成？它和 eval、APM 的边界在哪？agent 为什么不能直接套传统 APM？本章沿这三条线逐一拆开。

§1三方边界：可观测性 ≠ eval ≠ APM

三者都是"知道系统在干什么"的手段，但时机、对象、判据完全不同——混用会导致用了工具却解决不了问题。

APM 的契约在 agent 上为何失效

传统 APM 的核心假设是：状态码 = 健康信号。一个 HTTP 服务返回 200，APM 认为它正常。但 agent 违反这个假设，原因有四条：

• 语义失败对状态码不可见。差旅助理 agent 返回 status 200，给员工订了一张票——但这张票违反了差旅政策，或目的地是"巴黎"而正解是"里昂"。HTTP 层没有错，LLM 的推理在语义层出了问题，APM 对此完全盲。
• 非确定性打不了回归断言。同一个 prompt，同一个 seed，两次调用的输出未必逐字相同（温度 > 0 时更明显）。APM 期望的"同一请求 = 同一响应"契约不成立，所以不能像传统服务那样对输出做断言。
• token 与成本是一等信号，APM 从没有。一次 search_flights 失败触发重试，可能多刷了 4 次 chat，成本翻倍，延迟翻倍——APM 的延迟图看到的是一条慢请求，看不到是哪个子步骤在烧 token。
• 延迟来自外部 I/O，不是 CPU。agent 的延迟瓶颈 90% 是 LLM 推理（网络 RTT + 首 token 等待时间）和外部工具 API，不是本地计算。火焰图会照出一个巨大的"等待"空循环，找不到可优化的热点——它解决的是 CPU 密集型服务的问题，不是这里的问题。

这四条加在一起，决定了 agent 必须有自己的可观测性——而不是挂一个现成的 APM 就完事。

在线评估：三方的唯一接缝

三者之间存在一条接缝：在线评估（online evaluation）。scorer 对采样的生产 trace 打分、把分数写回 trace 成可查询字段，低分 trace 一键提拔进离线数据集，喂回 eval 的回归集——这是可观测性与 eval 相交的唯一点。第 3 章将详细展开；这里只需记住：这是运行期的外部 scorer 对生产 trace 打分，和 agent 推理时自己评自己纠错（Reflexion，属 agent-reasoning-patterns）完全不同。

§2trace 与 span：数据模型

一次 agent 运行 = 一个 trace（一棵 span 树）；span 是树上的最小工作单元，靠 parent_span_id 相连，没有 parent_span_id 的就是根。

在分布式追踪体系里，trace 代表一次端到端运行，全局唯一 trace_id。span 是 trace 里的一个工作单元，携带以下核心字段：

• trace_id：归属哪次运行（整棵树唯一）。
• span_id：本 span 的唯一标识。
• parent_span_id：父节点的 span_id；根 span 的该字段为空。
• name：操作名，如 chat / execute_tool: search_flights。
• kind：OTel 传输层分类（CLIENT / SERVER / INTERNAL），标记调用方向。
• attributes：类型化键值对，携带结构化元数据（如 gen_ai.request.model）。
• events：带时间戳的日志事件，携带大块或敏感内容（如 prompt / completion 文本）。
• status：OK / ERROR + 可选错误消息。
• start_time / end_time：用于计算 span 耗时。

这些 span 靠 parent_span_id 形成父子关系，整棵树就是这次运行的执行图——既是时序，也是因果。调试时沿父子链向上回溯，是定位根因的核心动作。

以「差旅助理 Agent」的一次典型运行为例，整棵 span 树如图 1.2 所示：

§3agent 的 span 层级

OTel GenAI 用 operation name 区分 span 语义（invoke_agent / chat / execute_tool / retriever）；OpenInference 在 OTel 传输层 kind 之上另加一套语义 kind，两套并存。

OTel 的传输层 kind（CLIENT / SERVER / INTERNAL）标记的是调用方向，不标记 LLM 操作的语义。GenAI semconv 在 name 字段里用 operation name 来区分语义：

• invoke_agent：编排根，代表一次完整的 agent 运行。v1.41.0（2025-04）将其拆成 CLIENT 和 INTERNAL 两类，以区分跨进程调用与进程内调用。
• chat：一次 LLM 调用（对应 chat completions API）。
• execute_tool：工具调用，名称通常带工具名（如 execute_tool: search_flights）。
• retriever：向量检索，如 retrieve_policy。
• create_agent：agent 实例化（如初始化带工具和系统 prompt 的 agent）。
• invoke_workflow：多 agent 编排时，调用一个下游 agent 或 workflow。

OpenInference（由 Arize 维护）在 OTel 之上加了一套语义 kind，放在 span 的 openinference.span.kind attribute 里，覆盖了 OTel 传输层 kind 无法表达的 LLM 专属语义：

§4一个 span 装什么

gen_ai.* attributes 携带模型元数据与 token 计数；prompt / completion 文本放在 events 而不是 attributes——因为敏感、体积大、且 opt-in；成本不在 OTel semconv 里，得厂商自己算。

一个典型 chat span 的 attributes 清单（基于 OTel GenAI semconv v1.41.0，2025-04）：

{
  "gen_ai.provider.name": "openai",
  "gen_ai.request.model": "gpt-4o",
  "gen_ai.response.model": "gpt-4o-2024-11-20",
  "gen_ai.usage.input_tokens": 1284,
  "gen_ai.usage.output_tokens": 312,
  "gen_ai.usage.reasoning.output_tokens": 0,
  "gen_ai.usage.cache_read.input_tokens": 800,
  "gen_ai.usage.cache_creation.input_tokens": 0,
  "gen_ai.response.finish_reasons": ["stop"],
  "gen_ai.response.time_to_first_chunk": 0.83
}

几个关键点：

• reasoning.output_tokens：o1 / R1 类推理模型的额外 token 计数，v1.41 加入。
• cache_read.input_tokens / cache_creation.input_tokens：prompt 缓存相关，v1.41 加入；可用于计算实际计费量。
• time_to_first_chunk：流式响应的首 token 等待时间，v1.41 加入；是用户感知延迟的关键指标。
• 成本不在 semconv：OTel 不定义 gen_ai.cost.*——有显式 usage 字段时，后端在 ingestion 阶段用 token 数 × 定价表算；没有 usage 字段时用对应 tokenizer 推算。这意味着成本数字在不同工具里可能有细微差异（定价表版本 / tokenizer 精度）。

§5分组与三支柱

多轮对话或跨请求的 session 用 gen_ai.conversation.id 分组；traces / metrics / logs 在 LLM 世界各自变形，但 trace（span 树）是主导。

分组：session / thread / conversation

一个 trace 代表一次请求-响应运行。当一个用户和 agent 进行多轮对话时，多条 trace 需要被归入同一个"会话"——这层分组各平台叫法不同：

各平台命名不同，但数据模型本质一致：会话 = 多条 trace 的逻辑分组，靠会话 ID 关联。user_id / tags / metadata 等业务标注从 trace 级下传到子 span，方便按用户、按功能模块查询。

三支柱在 LLM 世界的变形

可观测性的"三支柱"（traces / metrics / logs）在 LLM 世界各自发生了角色变化：

• traces 主导。span 树是执行图，是"为什么"的直接载体。LLM 应用的调试、根因分析、成本归因全靠它。
• metrics 退化为直方图。有意义的 metric 是 gen_ai.client.token.usage（token 分布）、operation.duration（操作耗时分布）、time_to_first_token（首 token 等待）。把 prompt 文本或 user-id 当 metric label 会引发基数爆炸（10 万+ 唯一值压垮时序数据库）。
• logs 降级为 span 上的 events。在 OTel 框架下，原来单独存放的日志行（"模型返回 stop"）现在作为带时间戳的 event 附在 span 上，上下文更完整。独立的日志流（print / logging）不再是主要手段。