企业官网建设流程全解析

系列：AI Agent 工程实践
上一篇：第 27 篇《日志系统（Logging）》
下一篇：第 29 篇《成本控制》

一、开场：LangSmith 为什么火

很多团队第一次用 LangSmith 都同一个反应："原来我的 Agent 每一步是这么想的。"之前只有一个最终回复，中间调了什么工具、卡在哪步、哪次模型抽风，全是一团黑盒。可视化的那一刻，调试从"玄学"变成"工程"。

上篇（27）讲了日志这个原料，这篇讲把它拼成"看得见"的能力——可观测性 Observability。

二、问题背景：日志 ≠ 可观测性

只有日志：

10:00 agent_run session=s_1 model=deepseek latency=850 10:00 tool_call name=get_weather 10:01 agent_run session=s_1 ...

可观测：

Trace t_1 (session=s_1, 总耗时 2.1s) ├─ Span agent_run 850ms │ ├─ Span llm_call 600ms (model=deepseek, tokens=1500) │ └─ Span tool_call 200ms (get_weather → 成功) └─ Span memory_read 50ms

差别：日志是"散落的事件"，可观测是"串起来的上下文链路"。

三、错误尝试：三种可观测翻车

错误 1：只有日志，没有 Trace

事件各自独立，无法回答"这次请求整体经历了什么"。查一个慢请求要手动拼时间线。

错误 2：Trace 不串联

每个步骤各自起一个 trace，没有父 ID 关联。看着有 trace，实则还是散的。

错误 3：只有链路，没有指标

能看单次请求，但无法回答"今天平均延迟多少、失败率多少"。缺聚合指标，容量规划靠猜。

四、关键观察：可观测 = 日志 + 链路 + 指标

三层：

1. Logs（事件）：发生了什么——由（27）提供。
2. Traces（链路）：一次请求怎么走的——Span 树，父 Span 串子 Span。
3. 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）、事件（日志）

字段表：

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", model="deepseek"): return llm(plan)

关键差异：每个操作用span包起来，自动形成树；model等属性挂在 Span 上，可在 UI 钻取。

七、设计权衡：自建 vs 托管

反过度工程：不要一上来就自建全套 APM。先托管看清价值，再按需自建。

八、总结

• ✅ 只有日志 = 黑盒；LangSmith 火在"看见每一步"。
• ✅ 三种翻车：无 Trace、Trace 不串联、只有链路没指标。
• ✅ 可观测 = Logs（事件）+ Traces（链路）+ Metrics（指标）。
• ✅ 核心是"一次请求能被还原成一棵可钻取的 Span 树"；OpenTelemetry 定义了标准。
• ✅ 反过度工程：先托管看清价值，再按需自建。

下一篇，用可观测喂来的数据做最实际的事——成本控制。（29）

参考资料（带用途说明）

• 本系列（27）日志系统（Logging）：本文的 Logs 层直接来自（27），Trace 在其上串联。
• 本系列（17）Agent 为什么需要可观测性：本文是（17）"为什么"对应的"怎么落地"。
• OpenTelemetry 文档（opentelemetry.io）：Trace/Span 标准与 SDK 来源。
• LangSmith 文档（docs.smith.langchain.com）：托管可观测方案的参考。

本文是 AI Agent 工程实践系列的第 28 篇（第四阶段第八篇）。

系列导航

上一篇：第 27 篇《日志系统（Logging）》
下一篇：第 29 篇《成本控制》