go语言分布式链路追踪必须从第一个http.handlerfunc起设计上下文传递和span注入，否则90%调用链断裂；otel.tracer须在main()开头初始化，goroutine需显式传ctx，gin/echo中间件应动态设span名，跨服务需用全小写traceparent并依赖propagator透传。
直接说结论：Go语言中嵌入分布式链路追踪，不是“学完再加”，而是从第一个 http.HandlerFunc 就该设计上下文传递和 span 注入——否则后期补追踪，90% 的服务调用链会断在中间。
go run 时 trace 不生效？检查 otel.Tracer 初始化时机
常见现象：本地跑通了示例代码，但实际 HTTP 请求进不来 trace ID；或 Jaeger 界面只看到单个 span，没有父子关系。
根本原因在于 OpenTelemetry SDK 必须在 main() 开头就完成初始化，且不能晚于任何 handler 注册。一旦 http.ServeMux 或 Gin/Echo 的路由树构建完成，再初始化 tracer 就无法拦截请求。
- ✅ 正确做法：在
main()最顶部调用initTracer()（含otel.SetTextMapPropagator和otel.SetTracerProvider） - ❌ 错误写法：把 tracer 初始化放在某个 handler 函数里、或依赖注入容器的 lazy init 阶段
- ⚠️ 注意：若用
go run main.go，确保main.go是入口文件；若用go build -o app ./cmd，则初始化必须在cmd/main.go中
goroutine 中 ctx 丢失？别用 context.Background() 启动子任务
典型场景：HTTP handler 里起 goroutine 做异步日志上报、缓存刷新或消息投递，结果这些操作完全不带 trace 上下文，链路在 fork 处断裂。
Go 的 context 是不可继承的——go func() { ... }() 默认不携带父 goroutine 的 ctx，必须显式传入。
- ✅ 正确写法：
go doAsyncWork(ctx, reqID)，且doAsyncWork第一个参数必须是context.Context - ❌ 危险写法：
go func() { log.Info("async done") }()—— 这里的log拿不到 span，也不会自动关联 trace ID - ? 提示：用
ctx = context.WithValue(ctx, key, value)传业务数据没问题，但别替代 span 传播；传播靠otel.GetTextMapPropagator().Inject()
Gin/Echo 中间件里 span 名称重复？避免硬编码 "handle-request"
现象：所有请求在 Jaeger 里都显示为 handle-request，无法区分是 /api/user 还是 /api/order，排查效率暴跌。
OpenTelemetry 要求 span 名体现操作语义，不是固定字符串。Gin 的 c.Request.URL.Path 和 Echo 的 c.Request().URL.Path 可直接用，但要注意路径参数需脱敏（如 /user/:id → /user/{id}）。
- ✅ 推荐方式：用
tracer.Start(ctx, c.Request().URL.Path)，再配合span.SetAttributes(attribute.String("http.method", c.Request().Method)) - ❌ 不推荐：
tracer.Start(ctx, "http-handler")—— 所有 span 名相同，失去可读性 - ⚠️ 兼容性注意：Gin v1.10+ 支持
c.Request().Context()直接继承，旧版需手动req = req.WithContext(ctx)
跨服务调用没 trace 透传？检查 header key 是否大小写敏感
现象：A 服务发 HTTP 请求到 B 服务，B 服务收不到 traceparent header，Jaeger 显示两个孤立 trace。
根本问题在 Go 的 http.Header 实现：它对 key 做了规范化（首字母大写，其余小写），而 W3C Trace Context 规范要求 header key 为全小写 traceparent 和 tracestate。如果 A 服务用 req.Header.Set("Traceparent", ...)，B 服务用 r.Header.Get("traceparent") 就拿不到。
- ✅ 正确做法：A 服务发送时用
req.Header.Set("traceparent", tp)（全小写 key）；B 服务接收时也用r.Header.Get("traceparent") - ? 更稳妥方案：用
otel.GetTextMapPropagator().Inject()和otel.GetTextMapPropagator().Extract()，它们内部已处理大小写兼容 - ⚠️ 注意：自定义 client 如
resty或gRPC需单独配置 propagator，不能只依赖 HTTP 默认行为
真正难的不是写通第一个 span，而是让 trace 在 goroutine 分叉、HTTP/gRPC 混合调用、中间件嵌套、异步队列等所有边界场景下都不丢——这需要把 context 作为函数第一参数的习惯刻进肌肉记忆，而不是当成“等出问题再加”的事后补丁。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
