Golang微服务链路追踪：Jaeger集成实践

先直接说结论：在Go微服务里集成Jaeger做链路追踪，有几个关键点一旦没处理好，整个trace链路就会断掉，排查起来相当头疼。

大家都知道，分布式系统的链路追踪是个基础能力，但Jaeger在Go语言里的集成细节往往容易被忽略。许多开发者以为照着官方文档配置一下就能跑起来，结果一上生产就发现数据对不上——不是某些操作没trace，就是上下游链路接不上。今天就把几个最容易被忽视的坑一次性说清楚。

service name 必须显式设置，否则 tracer 为 nil

你会踩的第一个坑：cfg.ServiceName 这个字段根本不是可选的。如果你漏掉了它，cfg.NewTracer() 会静悄悄地返回 nil，不报错、不警告。结果等你满怀信心地去调用 opentracing.GlobalTracer().StartSpan()，直接 panic：nil pointer dereference。

这种问题很少在单元测试阶段暴露，因为有些开发者只在集成测试里才启动tracer。

常见的错误用法包括：

• 直接 jaeger.NewConfig() 一把梭，但不去设置 ServiceName
• 把主机名、PID 或者时间戳塞进 service name，比如 "myapp-12345"，结果 Jaeger UI 里同一个服务的追踪数据被散成几十个条目，根本没法看
• 从环境变量 JAEGER_SERVICE_NAME 读取配置，但初始化顺序有问题——先调了 initTracer()，之后才用 os.Setenv() 去设置变量，等于没读到

正确的做法：在调用 NewTracer() 之前，明确写上 cfg.ServiceName = "order-service"。名称要稳定、小写、不带特殊字符，最好和部署单元的名字保持一致，比如 Kubernetes 里 Deployment 的名称。

HTTP 请求必须手动注入/提取 trace context

这是另一个容易踩的坑：Go 标准库的 http.Client 和 http.ServeMux 对 trace context 完全是“我不认识你是谁”的态度。uber-trace-id 或 traceparent 这些 Header 不会自动透传。客户端和服务端有一方没处理好，链路就断了。

客户端发请求前，需要手动注入：

err := tracer.Inject(span.Context(), opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(req.Header))
if err != nil { /* handle */ }

服务端收到请求时，得手动提取：

wireCtx, err := tracer.Extract(opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(r.Header))
if err != nil {
    span = tracer.StartSpan(r.URL.Path) // 无上游时新建 root
} else {
    span = tracer.StartSpan(r.URL.Path, opentracing.ChildOf(wireCtx))
}

需要注意的是，opentracing.HTTPHeaders 只是一个常量键，它不是自动触发行为。千万别手写 req.Header.Set("uber-trace-id", "...")——格式错一位，比如少传一个字节，Jaeger 就会丢弃整个 span，没有任何提示。

采样策略必须在创建 tracer 前配置

Jaeger 客户端的默认采样率是 1%。开发环境下，这个数值意味着你几乎看不到任何 trace。更致命的是，采样器不能在运行时动态调整，必须在 cfg.Sampler 里提前声明。

本地调试阶段，推荐全采：

• cfg.Sampler.Type = "const" + cfg.Sampler.Param = 1

生产环境就要看情况了：

• cfg.Sampler.Type = "probabilistic" + cfg.Sampler.Param = 0.01（1%）
• 如果用了 Jaeger Agent，可以换成 cfg.Sampler.Type = "remote"，由 Agent 统一决定采样策略

配置错误的后果很直接：设成 "const" 但 Param = 0，所有 span 被静默丢弃；如果是空字符串或者没设 Type，tracer 甚至初始化失败。

话说回来，生产环境该用多高的采样率？这取决于你的流量规模和成本。对于每秒几千请求的服务，1% 的采样率已经能提供足够的可观测性了。

span.Finish() 必须显式调用，且不能依赖 goroutine

这是一个非常隐蔽的坑，大部分开发者都是在排查“trace 为什么消失了”时才发现问题。不调 span.Finish()，span 就会一直滞留在内存里，既不发送给 Jaeger，也不会超时释放——除非你额外加了一个带 timeout 的 wrapper。

标准写法：

• 紧跟 span := tracer.StartSpan(...) 之后，立刻写 defer span.Finish()
• 不要在 goroutine 里启动 span 之后，又把 Finish() 也扔进 goroutine——执行时机不可控，非常容易丢失
• 如果遇到 panic 或提前 return，defer 会被跳过？那就用 if defer 或者显式 Finish() + recover() 兜底

举个例子：Gin 中间件里，只调了 StartSpan 但没有把 span 绑定到 r.Context() 上，后续的业务代码就拿不到当前 span，自然也 finish 不了它。这种问题最坑的地方在于——程序不报错，但数据就是传不上去。