04 可观测性:OpenTelemetry 贯穿

04 可观测性:OpenTelemetry 贯穿

本节摘要:这是第 12 章的收尾。一个能跑能交付的项目,还得「能懂」——运行时发生了什么、哪里慢、哪里错。OpenCode 用 OpenTelemetry 把可观测性贯穿到每一次工具执行、每一回合模型调用、每一次文件系统变更。本节讲清这套可观测性怎么布点、为什么「贯穿式」对调试和调优至关重要。

一、为什么需要可观测性

先想清楚没有可观测性的痛。Agent 跑了一次复杂任务,中途某步慢了或错了——你怎么定位?

• 没可观测性:只能靠日志瞎猜,或者重现问题加 print,效率极低。
• 有可观测性:看追踪(trace),哪一步花了多久、哪一步出错,一目了然。

可观测性让系统从「黑盒」变成「玻璃盒」。对 OpenCode 这种「多步骤、多工具、多模型调用」的系统尤其重要——一次任务可能调几十次工具、几次模型,没可观测性根本理不清。

二、OpenTelemetry:业界标准

OpenCode 用的可观测性方案是 OpenTelemetry——这是业界标准的可观测性框架。用它的好处:

• 统一:一套方案覆盖追踪、指标、日志,不用拼凑多个工具。
• 标准:数据格式标准,能接入各种后端(Jaeger、Prometheus、云厂商的可观测服务)。
• 生态丰富:各种语言/框架都有 OpenTelemetry 集成。

OpenCode 用 OpenTelemetry 把可观测数据(主要是追踪)导出,用户可以接到自己熟悉的可观测后端去看。

三、追踪(Span)的布点

可观测性的核心是追踪(trace),一个追踪由多个 **span(跨度)**组成,每个 span 代表一个操作。OpenCode 在关键环节都布了 span:

会话追踪(顶层 span)
   ├─ 回合1 span
   │    ├─ 模型调用 span(2s)
   │    ├─ 工具 read_file span(50ms)
   │    └─ 工具 edit_file span(80ms)
   ├─ 回合2 span
   │    ├─ 模型调用 span(1.5s)
   │    └─ 工具 bash span(500ms)
   └─ ...
​

这种「会话 → 回合 → 模型/工具」的层级追踪,让你能从宏观(整个会话)钻取到微观(某个工具某次调用)。

四、贯穿式可观测

「贯穿式」是 OpenCode 可观测性的特点——它不是只在某几个地方布点,而是贯穿所有关键环节:

• 工具执行有 span(第 5 章说的「自动加追踪」就是这个)
• 模型调用有 span(LLM 抽象层布点)
• 文件变更有快照(每回合捕获)
• 会话有顶层 span

这种贯穿让你能追踪「一次任务的完整轨迹」——从用户输入到模型响应到工具执行到文件变更,每一步都有记录。出问题时,你能精确定位是哪一步、哪一层的问题。

五、文件系统快照

除了 span,OpenCode 还在每个回合捕获文件系统快照——记录这次回合改了哪些文件。这让「Agent 改了什么」可追溯:

回合 N 结束
   │
   ▼ 捕获快照
快照: { 回合N 改了 [文件A(改), 文件B(删)] }
   │
   ▼ 发「回合结束」事件(含快照)
​

快照的价值:

• 审计:Agent 改了什么一目了然。
• 回滚:出问题时知道改了哪些,可针对性回滚。
• 可观测:配合 span,既有「过程」(工具调用)又有「结果」(文件变更)。

六、为什么贯穿式对调试和调优至关重要

贯穿式可观测对两个场景至关重要:

调试

出 bug 时,贯穿式追踪让你快速定位:

「Agent 改错了文件」
   │
   ▼ 看追踪
   │
   ▼ 回合3 的 edit_file span:改了文件X
   │
   ▼ 回合3 的模型调用 span:模型决定改X
   │
   ▼ 定位:是模型在那个回合做了错误决定
​

没有贯穿,你只能看到「文件X 被改了」,不知道是哪个回合、哪次模型调用、哪个工具改的。贯穿式让因果链完整。

调优

性能问题时,贯穿式让你看到「哪步慢」:

「这次任务跑了 30 秒,太慢」
   │
   ▼ 看追踪
   │
   ▼ 发现:回合5 的 bash span 花了 20 秒
   │
   ▼ 定位:某个命令执行太慢,优化它
​

没有贯穿,你只知道「总共 30 秒」,不知道时间花在哪。贯穿式让瓶颈可见。

七、第 12 章收尾:工程化的完整闭环

读完第 12 章四节,你掌握了 OpenCode 的工程化闭环:

这四节合起来,回答了「一个能跑的内核如何变成可交付、可运维、能懂的产品」。这是工业级项目与玩具项目的分水岭。第 13 章是全书最后一章,讲客户端契约、嵌入式 SDK 与二次开发。

本节要点回顾

1. 可观测性让系统从黑盒变玻璃盒:出问题能定位,调优有依据。
2. OpenTelemetry 业界标准:统一追踪/指标/日志,接各种后端。
3. span 布点:工具执行、模型调用、文件变更、会话,都有 span。
4. 贯穿式:所有关键环节都布点,不是只布几个。
5. 文件快照:每回合捕获改了哪些文件,可审计/回滚。
6. 调试+调优:贯穿式让因果链完整、瓶颈可见——这是工业级必备。
7. 第 12 章结束:配置管运行、编排管源码、构建管交付、观测管运维——工程闭环。

第 12 章结束。下一章是全书最后一章——客户端契约、嵌入式 SDK 与二次开发。