使用Go语言实现微服务链路追踪从入门到实践

先说几个关键判断：微服务链路追踪技术栈一旦选定，后期迁移成本极高。如果你还在使用 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 是否断裂。