1. 课程导学与背景：分布式系统下日志与追踪的挑战
1.1 从单体到分布式：日志的“盲区”
在单体应用时代，排查问题通常很简单：登录服务器，查看单个日志文件，按时间戳搜索关键词即可定位故障。然而，当系统演进为微服务架构后，一个用户请求往往需要跨越数十甚至上百个服务节点才能完成。此时，传统的日志管理方式暴露出三个核心痛点：
- 日志碎片化：每个服务独立输出日志，缺乏全局请求标识，无法将一次请求的完整调用链串联起来。
- 时序错乱：分布式环境下各服务器时钟不同步，导致跨服务的日志时间戳无法准确排序。
- 根因定位困难：面对海量日志，手动搜索耗时巨大，且难以判断到底是哪个服务、哪段代码导致了延迟或错误。
典型案例：某电商平台大促期间，用户反馈“下单后未收到确认消息”。运维团队在 20 多个微服务的日志中手动搜索了 3 小时，才发现是“库存服务”调用“通知服务”时因网络超时导致消息丢失。如果当时有链路追踪，这个问题可以在 5 分钟内定位。
1.2 分布式链路追踪的核心概念
为了解决上述问题，业界提出了分布式链路追踪（Distributed Tracing）技术。其核心思想是为每个外部请求分配一个全局唯一的 TraceID，并在请求经过的每个服务内部生成 SpanID，通过父子 Span 关系构建出一棵完整的调用树。
| 概念 | 说明 | 类比 |
|---|---|---|
| Trace | 一次完整的请求链路，从入口到所有下游服务返回 | 一次完整的快递配送过程 |
| Span | Trace 中的一个工作单元，记录服务名称、开始/结束时间、状态等 | 快递从仓库到分拣中心的这一段运输 |
| TraceID | 全局唯一标识，贯穿整个请求链路 | 快递单号 |
| SpanID | 每个 Span 的唯一标识，通过 ParentSpanID 关联父子关系 | 每段运输的运单编号 |
1.3 日志埋点与链路追踪的关系
日志埋点（Logging Instrumentation）与链路追踪（Tracing）并非相互替代，而是互补关系：
- 链路追踪：提供请求级别的调用拓扑和延迟分布，回答“请求经过了哪些服务？每个服务耗时多少？”
- 日志埋点：在关键业务逻辑处输出结构化日志，回答“这个服务在处理请求时，内部发生了什么？业务数据是什么？”
最佳实践是将两者结合：在日志中注入 TraceID 和 SpanID，使得从追踪系统发现异常 Span 后，可以一键跳转到对应服务的详细日志上下文。
实践建议：在 Go 项目中，推荐使用 OpenTelemetry SDK 统一管理 Trace 和日志上下文。通过
context.Context 传递 TraceID，并在日志库（如 zap、logrus）中自动注入该 ID，实现“一次埋点，双重收益”。
1.4 课程目标与学习路径
本课程旨在帮助 Go 开发者从零构建一套生产可用的分布式日志与链路追踪体系。完成本课程后，你将能够：
| 模块 | 核心能力 | 关键产出 |
|---|---|---|
| 基础篇 | 理解 Trace/Span 模型，掌握 OpenTelemetry Go SDK 基础用法 | 一个可运行的链路追踪 Demo |
| 进阶篇 | 实现日志与 Trace 的自动关联，设计结构化日志格式 | 日志-追踪联动查询方案 |
| 实战篇 | 在 gRPC/HTTP 服务中集成全链路埋点，对接 Jaeger/Zipkin | 生产级埋点中间件 |
| 运维篇 | 采样策略、性能优化、告警与可视化 | 分布式追踪运维手册 |
1.5 为什么选择 Go 语言实现？
Go 语言在云原生和微服务领域占据主导地位，其并发模型和标准库特性使得链路追踪的落地更加自然：
- context.Context：Go 原生提供的上下文传递机制，天然适合携带 TraceID 和 SpanID 跨协程传播。
- 高性能：Go 的 goroutine 和零拷贝特性，使得埋点带来的性能损耗极低，适合高并发生产环境。
- 生态成熟：OpenTelemetry 官方对 Go 的支持非常完善，主流框架（gin、gRPC、echo）均有现成中间件。
避坑提示：不要试图在业务代码中手动拼接 TraceID 字符串。必须使用 OpenTelemetry 的
propagation 包自动注入和提取上下文，否则在跨进程传递时极易出现 ID 丢失或格式不一致的问题。