应使用OpenTelemetry替代已归档的jaeger-client-go，因其自2024年底起不再维护，存在安全风险、context透传失效、Span断链及CI构建失败等问题；OpenTelemetry是CNCF毕业项目，Go SDK活跃维护，原生支持Jaeger后端且兼容OTLP、Zipkin等多后端。
为什么直接用 opentelemetry-go 而不是 jaeger-client-go
因为 jaeger-client-go 已归档，官方明确推荐迁移到 OpenTelemetry。继续用它会导致无法接收新特性、安全补丁缺失，且与当前主流后端（如 Jaeger、Zipkin、OTLP 接收器）的兼容性逐渐变差。OpenTelemetry 是云原生可观测性的事实标准，Go SDK 维护活跃，API 稳定。
常见错误现象：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。
立即学习“go语言免费学习笔记（深入）”；
- 服务端：用
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 = Unavailable 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 是否断裂。
