使用Go语言实现微服务链路追踪

应使用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 是否断裂。