可观测性工程概要：前言
00｜前言：为什么要学习可观测性工程
软件系统越来越复杂，但工程师看到的往往只是几个结果：请求变慢了、错误率升高了、用户开始投诉了。至于系统内部究竟发生了什么，常常要靠经验、猜测和临时加日志。
可观测性工程要解决的，正是这种“看见结果，却看不清过程”的困境。
从监控系统走向理解系统
传统监控擅长发现已知问题。我们提前设置 CPU、内存、错误率和响应时间的阈值，系统越界后触发告警。这套方式依然重要，但它有一个天然限制：只有提前想到的问题，才容易被监控发现。
现实中的故障却很少完全按照预案出现。一次延迟升高，可能只影响某个版本、某类用户或一条特殊调用路径。如果数据只剩下平均值，我们很难从中找到这些细节。
可观测性强调保留足够丰富的上下文，让工程师能够在问题发生后继续提问：谁受到了影响？从哪个版本开始？经过了哪些服务？在哪一步出现偏差？
一个简单案例
用户要求报告 Agent 搜索资料并生成摘要。某天开始，部分报告缺少关键数据。最终答案看起来像“模型变笨了”，但完整执行记录显示：搜索工具已经返回正确结果，Harness 在合并分页数据时遗漏了最后一页。
这个案例说明，Agent 的结果由模型、上下文、Harness、工具和外部依赖共同决定。只看最终答案，很容易把系统问题误判为模型能力问题。
现实挑战：我们甚至不知道应该怀疑谁
现象—假设—证据—判断
现象：报告偶发缺少数据。假设包括模型忽略信息、工具返回不完整、Harness 解析失败、上下文被截断。证据显示工具原始返回完整，模型输入中却没有最后一页数据。判断：问题发生在 Harness 的结果合并阶段。
可观测性的价值，是让每个假设都能找到对应证据，而不是依赖经验争论“是不是模型不行”。
这不是“三大支柱”的简单集合
日志、指标和链路追踪经常被称为可观测性的三大支柱，但同时拥有三套工具，并不意味着系统已经具备可观测性。
真正重要的是，这些数据能否围绕一次请求或任务关联起来，能否支持高维度、高基数的查询，能否帮助我们调查此前没有预料到的问题。
对于 Agent 软件设计与开发，这一点更加明显。一次任务可能经历规划、模型调用、检索、工具调用、重试和最终回答。
只记录请求成功率，并不能解释 Agent 为什么做出某个决定，也无法判断问题来自模型、提示词、工具还是工作流。
OpenTelemetry在学习中的位置
可观测性工程提供方法和思维框架，OpenTelemetry 提供跨语言的工程规范。它统一了 Trace、Metric、Log、Resource、上下文传播和数据传输等概念，也通过语义约定统一常见字段的命名方式。
学习过程中，我们不会把 OpenTelemetry 当成一套需要背诵的 API，而是把它当作验证设计的坐标：一次任务怎样表示为 Trace？一个执行步骤怎样表示为 Span？哪些字段适合聚合，哪些字段只适合定位单次运行？数据如何经过 Collector 到达后端？
我们要形成什么能力
这次学习不会停留在章节摘要。每个主题都要留下可以继续使用的成果：一篇讲义、一张白底配图，以及一份字段表、Trace 设计、采样策略或架构方案。
最终，我们希望具备一条完整的分析路径：
告警发现异常
↓
查询受影响的请求或任务
↓
沿 Trace 还原执行过程
↓
定位具体服务、模型或工具
↓
解释根因并验证修复
学习目标
- 解释监控与可观测性的区别；
- 理解 Trace、Metric、Log、Event 和 Resource；
- 掌握 OpenTelemetry API、SDK、OTLP 与语义约定；
- 能为 Agent 设计维度、基数、链路、采样和隐私策略；
- 能从告警出发，定位到具体任务、步骤、模型或工具。
学习路线
| 阶段 | 学习主题 | 主要成果 |
|---|---|---|
| 00 | 前言：为什么要学习可观测性工程 | 学习地图、目标与方法 |
| 01 | 可观测性的基本概念 | 概念讲义、关键术语表 |
| 02 | 监控与可观测性 | 对比文章、白底对比图 |
| 03 | 遥测数据模型 | Trace 与 Span 结构图 |
| 04 | OpenTelemetry API 与 SDK | 组件关系图、埋点示例 |
| 05 | OTLP 与 Collector | 遥测数据流架构图 |
| 06 | Semantic Conventions | 字段设计表、命名规范 |
| 07 | Agent 与 GenAI 可观测性 | Agent Trace 设计图 |
| 08 | 基数、采样、成本与隐私 | 采样策略、数据分层表 |
| 09 | 综合架构设计 | Agent 可观测性架构方案 |
| 10 | Evaluation Engineering | 自动评估闭环、评估数据模型 |
| 11 | Runtime实时高可靠可观测性 | 运行时保护闭环、可靠性信号 |
小结
可观测性不是为了收集更多数据，而是为了提高理解系统的能力。它要求我们在系统设计阶段，就考虑未来需要提出哪些问题，以及发生未知故障时是否还保留了足够的线索。
接下来的学习将从基本概念开始，逐步进入遥测模型、OpenTelemetry、Agent 场景、评估工程和 Runtime 高可靠架构。