Golang 结合 OpenTelemetry 实现分布式追踪

好的，作为一名在可观测性领域摸爬滚打多年的老手，今天跟各位聊聊 Golang 分布式追踪里那些“看似懂了，一配就断”的坑。 很多朋友上手 OpenTelemetry，照着文档噼里啪一顿配，觉得该写的都写了。结果打开 Jaeger 一看，空空如也，或者链路断成了好几截。问题出在哪？十个里有九个是下面这三个地方没搞对。 先说一个最基础的，也是最容易让人心态爆炸的点：采样器和传播器。这两个东西是亲兄弟，缺一不可。必须显式配好，比如用 `sdktrace.ParentBased(sdktrace.TraceIDRatioBased(0.01))` 来做采样策略，同时通过 `otel.SetTextMapPropagator` 把传播器设对。这两样没办妥，后果就是：既不生成 span，上下文也无法在服务间透传。整个链路，第一跳就直接折了。 直接上手，把 `TracerProvider`、采样器和导出器都配好，跑通 Demo 确实不难。但难点在于，不配采样器、不设传播器、或者忘了给 HTTP handler 套上中间件，那 90% 的线上链路都会在第一跳死得透透的。 ### 为什么 otelhttp.NewHandler 包裹后还是没 server span？ 很多时候，你明明已经用了 `otelhttp.NewHandler` 来包裹处理函数，但服务端就是不出 span。别怀疑中间件失效，大概率是 handler 根本就没被注册到路由上。 常见的翻车姿势有这么几种： * **忘换代码**：只写了 `http.Handle("/api", myHandler)`，但没换成 `http.Handle("/api", otelhttp.NewHandler(myHandler, "api"))`。这一步是入口，必须改。 * **Gin 框架的特殊处理**：在 Gin 里，直接传原始 `http.HandlerFunc` 是不行的，要通过 `gin.WrapH(otelhttp.NewHandler(...))` 才行。 * **空 Span Name**：`otelhttp.NewHandler` 的第二个参数，也就是 span 的名字，千万别传空字符串。部分导出器（比如 Jaeger）遇到空的 span name 会直接丢弃。 * **Handler 内部异常**：如果 handler 内部发生了 panic 或提前 return，导致 `defer span.End()` 没执行，那这个 span 就会被静默丢弃，日志都看不出来。 ### 采样器配置错或漏掉，trace 就全空 `oteltrace.Tracer` 的默认行为是 `sdktrace.NeverSample()`，翻译过来就是“给我往死里空跑”。它会让你以为采集成效不错，实则数据全无。现象就是 Jaeger 或 Tempo 里啥也没有，日志还不报错。 要解决这个问题，必须在 `sdktrace.NewTracerProvider()` 里显式传入 `sdktrace.WithSampler(...)`。但要注意，生产环境别一股脑用 `sdktrace.AlwaysSample()` —— 一旦 QPS 上千，exporter 会立马积压、重试风暴，最后把网络拖垮。 必须配置 `sdktrace.ParentBased(sdktrace.TraceIDRatioBased(0.01))`。这样做的好处是：如果上游链路没被采样，下游即使想采，也收不到 `traceparent` 头，整条链路自然就消失了。另外，采样率写死在代码里非常不灵活。聪明的做法是用环境变量读取，加个校验（比如值大于 1 就自动设为 0.001），再包一层可变 `Sampler`，配合信号实现热重载，这才是真正的生产级用法。 ### goroutine 和数据库调用里 trace 断开的真相 Go 的 `context.Context` 不跨 goroutine 自动传递，这是 Go 分布式追踪最底层、也最容易被忽略的事实。DB 驱动也不会自动读取 context 里的 span。 怎么办？记住这几条铁律： * **启动新 goroutine**：必须显式传入带 span 的 context。比如 `go doWork(ctx)`，然后在函数内用 `trace.SpanFromContext(ctx)` 获取父级 span。 * **异步逻辑**：对于 `time.AfterFunc`、`sync.WaitGroup` 这类异步操作，同样要传 `ctx`，并用 `context.WithTimeout` 控制其生命周期。 * **数据库查询**：必须用 `db.QueryContext(ctx, ...)`，不能用 `db.Query(...)`。如果用的是 GORM，记得调用 `WithContext(ctx)`。 * **跨进程传递**：`context.WithValue` 在跨进程场景是无效的。HTTP 出站必须靠 `propagator.Inject(ctx, carrier)` 写入请求头，而不是靠塞值。 ### 导出器选 OTLP 还是 Jaeger？关键看阶段 本地开发用 Jaeger agent 体验最好，跑个 `docker run -p 6831:6831 jaegertracing/all-in-one` 就能用。但生产环境，直连 OTLP endpoint 是硬性要求——这不仅关乎性能，更是协议和生态的倒逼。 * Jaeger 的 thrift 协议早已被弃用，新版只支持 OTLP。旧版使用的 `uber-trace-id` 头不兼容 W3C 标准，跨语言对接时容易出幺蛾子。 * Zipkin 的时间精度只有毫秒级，而 OpenTelemetry 默认是纳秒级。转换时会丢精度，而且不支持 baggage。 * **开发阶段**：用 `jaeger.NewExporter(jaeger.WithAgentEndpoint())` 快速上手。 * **生产阶段**：用 `otlphttp.NewExporter(otlphttp.WithEndpoint("https://your-otlp-endpoint/v1/traces"))`，必须配好 TLS 和认证。这可是截至 2026 年 4 月的通行做法。 最后，说一个几乎所有人都踩过的坑：采样器初始化和传播器设置的**顺序**。一定要先设 `otel.SetTextMapPropagator`，再建 `TracerProvider`。否则，`Extract/Inject` 时用的就是默认的 noop propagator，header 完全透传不出去。 记住这个顺序，链路就接上了。不是链路慢，是你没连对。