先说几个关键判断：微服务链路追踪技术栈一旦选定，后期迁移成本极高。如果你还在使用 jaeger-client-go，现在就是做出决策的关键时刻——这个库从2024年底起已停止维护，继续依赖它，相当于在生产环境中埋下隐患。
问题远不止“没人修复bug”那么简单。安全风险、context透传失效、Span断链、CI构建失败……这些隐患会随着依赖版本迭代逐一暴露。而OpenTelemetry已是CNCF的毕业项目，Go SDK正在积极维护，既能原生对接Jaeger后端，也能兼容OTLP、Zipkin等多种后端。说白了，它就是当前链路追踪领域的事实标准，而非可选项。
为什么直接使用 opentelemetry-go 而非 jaeger-client-go
市面上确实还有一些遗留项目在跑jaeger-client-go，但现实是它已经归档了。官方推荐迁移到OpenTelemetry，这不仅是建议，而是唯一正确的方向。继续使用它，意味着新特性、安全补丁将与你无关，而且与主流后端（如Jaeger、Zipkin、OTLP接收器）的兼容性会越来越差。
常见错误现象：import "github.com/uber/jaeger-client-go" 编译通过但上报失败；或者调用 tracer.StartSpan() 后 span 没有任何数据落库——大概率是 reporter 未 flush 或 client 已停服。
- 必须使用
go.opentelemetry.io/otel/sdk/trace构建 trace provider，不能直接 new tracer - 初始化时务必调用
tp.Shutdown(context.Background())，否则进程退出前 span 可能丢失 - 默认采样器是
trace.AlwaysSample()，线上需换成trace.ParentBased(trace.TraceIDRatioBased(0.01))控制上报量
如何让 HTTP 请求自动注入/提取 trace context
Go 标准库 http.ServeMux 和第三方路由（如 gin、echo）都不自带 tracing 中间件，必须手动包装 handler 或注册 middleware。
场景很明确：服务 A 通过 http.Client 调用服务 B，B 的 handler 需要从 req.Header 解析 traceparent 并延续 span；A 发起请求时也得把当前 span context 注入到 req.Header。
- 服务端：用
otelhttp.NewHandler()包裹你的 handler，它会自动从traceparent提取 context 并创建 child span - 客户端：用
otelhttp.NewClient()替代原生http.Client，它会在每次Do()前注入traceparent - 不要自己解析
req.Header.Get("traceparent")—— OpenTelemetry 的propagation.HTTPTraceContext已经处理了 W3C 格式的细节，手动解析极易出错
context.Context 传参不生效？检查 span 是否被 cancel 或超时
Go 微服务中常把 ctx 从 handler 一路透传到 DB 查询、RPC 调用，但 span 丢失最常见的原因就是 context.WithTimeout() 或 context.WithCancel() 提前结束，导致 span close 被跳过。
一个非常典型的错误：在 handler 内写 ctx, cancel := context.WithTimeout(r.Context(), 500*time.Millisecond)，然后 defer cancel() —— 这会让 span 在 handler 结束前就被终止，即使后续 DB 操作耗时 800ms，该 span 也不会被上报。
- span 生命周期应该绑定业务逻辑，而不是 HTTP 请求生命周期；用
trace.WithNewRoot()创建独立 span 会更安全 - 如果必须使用 timeout，确保在 span.End() 之后再 cancel，或者用
context.WithValue(ctx, key, span)显式携带 span 实例 - 调试时加
log.Printf("span %s: %v", span.SpanContext().TraceID(), span.SpanContext().SpanID())确认是否为空
本地开发时 span 上报不到 Jaeger？重点查 OTLP endpoint 和 exporter 配置
本地运行 docker run -d -p 16686:16686 -p 4317:4317 jaegertracing/all-in-one 后，span 仍然不上报，90% 的情况是 exporter 地址或协议不匹配。
错误现象：otel-collector 日志无 error，但 Jaeger UI 为空；或者 Go 程序启动时报 failed to export: rpc error: code = Una vailable desc = connection error。
- 确认 exporter 使用的是
otlpgrpc.NewExporter()（对应 4317 端口），而不是otlphttp.NewExporter()（默认走 4318） - endpoint 地址写
"localhost:4317"，不要写"127.0.0.1:4317"—— Docker 容器内 localhost 不指向宿主机 - 如果使用
otel-collector而非 all-in-one，检查 collector 配置里是否启用了otlp:receiver 和jaeger:exporter
真正复杂的地方在于 span 层级嵌套和异步 goroutine 的 context 传递——一旦漏掉 context.WithValue() 或用错 context.TODO()，父子关系就断了。这一点没法靠工具自动发现，只能靠日志打点配合 Jaeger UI 查看 span tree 是否断裂。
