Go链路追踪断裂主因是context.Context未正确传递：必须为首参、用私有类型key存取、HTTP中间件需显式替换r.Context()、goroutine须显式传ctx，禁存ctx到struct。
Go 里链路追踪断掉，90% 是因为 context.Context 没传对、没传全，或者 key 写错了——不是 SDK 不好用，是上下文本身被破坏了。
context.Context 必须是函数第一个参数
OpenTelemetry、Jaeger、Datadog 等 tracing SDK 都依赖这个约定：从调用栈向上扫描，自动提取父 span。一旦 ctx 不在第一位，工具链就找不到它。
- ✅ 正确：
func ProcessOrder(ctx context.Context, orderID string) error - ❌ 错误：
func ProcessOrder(orderID string, ctx context.Context) error（span 关联失败） - ❌ 错误：
func ProcessOrder(req OrderRequest) error（req.ctx是黑盒，SDK 无法识别）
尤其注意中间件和 handler 之间：Gin/Echo 的 HandlerFunc 入参是 *http.Request，你得手动从 r.Context() 取，再确保下游每个函数都接收并透传这个 ctx。
traceID key 绝不能用 string
ctx.Value("trace_id") 在单个文件里可能跑通，跨包就必然返回 nil。Go 的 ctx.Value() 比较 key 是按内存地址（==），两个包各自写的 "trace_id" 字符串不是同一个对象。
立即学习“go语言免费学习笔记（深入）”；
- ✅ 正确做法：定义私有 struct 类型，全局唯一实例
type traceKey struct{}var traceKeyKey = traceKey{}
存：ctx = context.WithValue(ctx, traceKeyKey, id)
取：id := ctx.Value(traceKeyKey).(string) - ⚠️ 注意：类型断言要加
ok判断，避免 panic；key 类型必须未导出（小写开头），否则其他包也能定义同名类型造成冲突
HTTP 中间件注入后 downstream 拿不到 traceID
常见错因不是没生成，而是没把新 context 绑回 *http.Request。中间件里调了 context.WithValue(r.Context(), ...)，但忘了 r = r.WithContext(newCtx)，后续 handler 拿到的仍是原始 request。
- ✅ 必须在中间件末尾显式替换：
r = r.WithContext(ctx)，再调next.ServeHTTP(w, r) - ✅ 优先解析标准 header：
traceparent（W3C）→X-Trace-ID→X-Request-ID；注意X-Request-ID不保证唯一，仅作保底 - ✅ 生成新 ID 仅限上游完全未传时；一旦 header 有值，必须复用，禁止覆盖
goroutine 启动时 traceID 突然变空
Go 的 go fn() 不会自动继承父 goroutine 的 context。闭包捕获的是变量引用，而那个 ctx 可能早已被 cancel，或压根没注入 traceID。
- ✅ 唯一可靠方式：显式传参
go func(ctx context.Context) { log.Printf("trace: %s", TraceIDFromContext(ctx)) }(r.Context()) - ❌ 危险写法：
go func() { ... }(r.Context())（闭包捕获的是未注入 traceID 的旧 ctx） - ⚠️ 所有异步操作（DB 查询、HTTP 调用、消息发送）都需派生子 context，比如
ctx, cancel := context.WithTimeout(parentCtx, 5*time.Second)，再传入
最隐蔽的坑是把 context.Context 存进 struct 长期持有——取消信号失效、goroutine 泄漏、traceID 错乱，三者必中其一。
