系列AI Agent 工程实践上一篇第 27 篇《日志系统Logging》下一篇第 29 篇《成本控制》一、开场LangSmith 为什么火很多团队第一次用 LangSmith 都同一个反应原来我的 Agent 每一步是这么想的。之前只有一个最终回复中间调了什么工具、卡在哪步、哪次模型抽风全是一团黑盒。可视化的那一刻调试从玄学变成工程。上篇27讲了日志这个原料这篇讲把它拼成看得见的能力——可观测性 Observability。二、问题背景日志 ≠ 可观测性只有日志10:00 agent_run sessions_1 modeldeepseek latency850 10:00 tool_call nameget_weather 10:01 agent_run sessions_1 ...可观测Trace t_1 (sessions_1, 总耗时 2.1s) ├─ Span agent_run 850ms │ ├─ Span llm_call 600ms (modeldeepseek, tokens1500) │ └─ Span tool_call 200ms (get_weather → 成功) └─ Span memory_read 50ms差别日志是散落的事件可观测是串起来的上下文链路。三、错误尝试三种可观测翻车错误 1只有日志没有 Trace事件各自独立无法回答这次请求整体经历了什么。查一个慢请求要手动拼时间线。错误 2Trace 不串联每个步骤各自起一个 trace没有父 ID 关联。看着有 trace实则还是散的。错误 3只有链路没有指标能看单次请求但无法回答今天平均延迟多少、失败率多少。缺聚合指标容量规划靠猜。四、关键观察可观测 日志 链路 指标三层Logs事件发生了什么——由27提供。Traces链路一次请求怎么走的——Span 树父 Span 串子 Span。Metrics指标总体健康度——成功率、P95 延迟、成本曲线。可观测的核心不是能看到日志是一次请求能被还原成一棵可钻取的树。这也是 OpenTelemetry 进入 AI 的原因——它定义了 Trace/Span 的标准让任何框架的链路都能互通。五、最终方案Trace 结构长什么样Trace t_1 (一次用户请求) ├─ Span: agent_run # 根 │ ├─ Span: planner # 决定下一步 │ ├─ Span: llm_call # 调模型 │ ├─ Span: tool_call(email) # 调工具 │ └─ Span: memory_read └─ 每个 Span 带起止时间、属性model/tokens、事件日志字段表概念含义Trace一次完整请求的生命周期Span链路中的一个节点一次操作ParentSpan 的父节点构成树AttributeSpan 上的结构化属性EventSpan 内发生的离散日志Span 树Mermaid六、代码对比无 trace vs 有 trace无 trace问题def run_agent(inp): plan planner(inp) # 看不见耗时归属 return llm(plan)有 trace生产from monitor.trace import trace def run_agent(inp): with trace(agent_run) as root: with root.span(planner): plan planner(inp) with root.span(llm_call, modeldeepseek): return llm(plan)关键差异每个操作用span包起来自动形成树model等属性挂在 Span 上可在 UI 钻取。七、设计权衡自建 vs 托管场景建议理由起步 / 验证托管LangSmith 类开箱即用快速看见数据敏感 / 合规自建 Otel 自有存储数据不出域多框架统一OpenTelemetry 标准跨框架互通反过度工程不要一上来就自建全套 APM。先托管看清价值再按需自建。八、总结✅ 只有日志 黑盒LangSmith 火在看见每一步。✅ 三种翻车无 Trace、Trace 不串联、只有链路没指标。✅ 可观测 Logs事件 Traces链路 Metrics指标。✅ 核心是一次请求能被还原成一棵可钻取的 Span 树OpenTelemetry 定义了标准。✅ 反过度工程先托管看清价值再按需自建。下一篇用可观测喂来的数据做最实际的事——成本控制。29参考资料带用途说明本系列27日志系统Logging本文的 Logs 层直接来自27Trace 在其上串联。本系列17Agent 为什么需要可观测性本文是17为什么对应的怎么落地。OpenTelemetry 文档opentelemetry.ioTrace/Span 标准与 SDK 来源。LangSmith 文档docs.smith.langchain.com托管可观测方案的参考。本文是 AI Agent 工程实践系列的第 28 篇第四阶段第八篇。系列导航上一篇第 27 篇《日志系统Logging》下一篇第 29 篇《成本控制》