00｜前言：为什么要学习可观测性工程

《可观测性工程》学习讲义 · 前言

软件系统越来越复杂，但工程师看到的往往只是几个结果：请求变慢了、错误率升高了、用户开始投诉了。至于系统内部究竟发生了什么，常常要靠经验、猜测和临时加日志。

可观测性工程要解决的，正是这种“看见结果，却看不清过程”的困境。

从监控系统走向理解系统

传统监控擅长发现已知问题。我们提前设置 CPU、内存、错误率和响应时间的阈值，系统越界后触发告警。这套方式依然重要，但它有一个天然限制：只有提前想到的问题，才容易被监控发现。

现实中的故障却很少完全按照预案出现。一次延迟升高，可能只影响某个版本、某类用户或一条特殊调用路径。如果数据只剩下平均值，我们很难从中找到这些细节。

可观测性强调保留足够丰富的上下文，让工程师能够在问题发生后继续提问：谁受到了影响？从哪个版本开始？经过了哪些服务？在哪一步出现偏差？

一个简单案例

用户要求报告 Agent 搜索资料并生成摘要。某天开始，部分报告缺少关键数据。最终答案看起来像“模型变笨了”，但完整执行记录显示：搜索工具已经返回正确结果，Harness 在合并分页数据时遗漏了最后一页。

这个案例说明，Agent 的结果由模型、上下文、Harness、工具和外部依赖共同决定。只看最终答案，很容易把系统问题误判为模型能力问题。

现实挑战：我们甚至不知道应该怀疑谁

现象—假设—证据—判断

现象：报告偶发缺少数据。假设包括模型忽略信息、工具返回不完整、Harness 解析失败、上下文被截断。证据显示工具原始返回完整，模型输入中却没有最后一页数据。判断：问题发生在 Harness 的结果合并阶段。

可观测性的价值，是让每个假设都能找到对应证据，而不是依赖经验争论“是不是模型不行”。

这不是“三大支柱”的简单集合

日志、指标和链路追踪经常被称为可观测性的三大支柱，但同时拥有三套工具，并不意味着系统已经具备可观测性。

真正重要的是，这些数据能否围绕一次请求或任务关联起来，能否支持高维度、高基数的查询，能否帮助我们调查此前没有预料到的问题。

对于 Agent 软件，这一点更加明显。一次任务可能经历规划、模型调用、检索、工具调用、重试和最终回答。只记录请求成功率，并不能解释 Agent 为什么做出某个决定，也无法判断问题来自模型、提示词、工具还是工作流。

OpenTelemetry在学习中的位置

《可观测性工程》提供方法和思维框架，OpenTelemetry 提供跨语言的工程规范。它统一了 Trace、Metric、Log、Resource、上下文传播和数据传输等概念，也通过语义约定统一常见字段的命名方式。

学习过程中，我们不会把 OpenTelemetry 当成一套需要背诵的 API，而是把它当作验证设计的坐标：一次任务怎样表示为 Trace？一个执行步骤怎样表示为 Span？哪些字段适合聚合，哪些字段只适合定位单次运行？数据如何经过 Collector 到达后端？

我们要形成什么能力

这次学习不会停留在章节摘要。每个主题都要留下可以继续使用的成果：一篇讲义、一张白底配图，以及一份字段表、Trace 设计、采样策略或架构方案。

最终，我们希望具备一条完整的分析路径：

告警发现异常
    ↓
查询受影响的请求或任务
    ↓
沿 Trace 还原执行过程
    ↓
定位具体服务、模型或工具
    ↓
解释根因并验证修复

小结

可观测性不是为了收集更多数据，而是为了提高理解系统的能力。它要求我们在系统设计阶段，就考虑未来需要提出哪些问题，以及发生未知故障时是否还保留了足够的线索。

接下来的学习将从基本概念开始，逐步进入遥测模型、OpenTelemetry、Agent 场景、评估工程和 Runtime 高可靠架构。

---

可观测性工程系列：下一篇：01｜可观测性工程概要：从系统输出理解内部状态

原文：LandX