如何在Golang微服务中引入Jaeger作为无侵入链路追踪

jaeger-client-go 并非真正无侵入，需手动调用追踪API；实际“无侵入”指通过 otelhttp、otelgin、otelgrpc 等中间件最小化业务代码修改，核心是正确传递 context 以保证 trace 链路完整。

jaeger-client-go 本身不是无侵入的——它必须手动调用 StartSpan、Inject、Extract，也没有自动拦截 HTTP/gRPC 的能力。所谓“无侵入”，实际是指**尽量减少业务代码修改**，靠中间件/包装器封装追踪逻辑。真零修改做不到，但可以压到最小。

用 otelhttp 中间件替代手写 HTTP trace 注入

Go 标准库 http 不会自动传播 trace header，但 otelhttp 能在不改 handler 函数签名的前提下完成上下文提取、Span 创建与注入。

• 替换 http.ListenAndServe 为 otelhttp.NewHandler 包装的 handler
• 确保 otel.SetTextMapPropagator 已设为 propagation.TraceContext{}（W3C 标准，兼容现代 Jaeger）
• 别混用 opentracing 和 otel API：二者不互通，otelhttp 只认 OpenTelemetry context
• 示例：http.ListenAndServe(":8080", otelhttp.NewHandler(http.DefaultServeMux, "my-service"))

gin-gonic 里加 otelgin.Middleware 就够了

如果你用 Gin，otelgin.Middleware("my-service") 会自动做三件事：从 req.Header 提取 traceparent、创建 server span、把 span 绑定到 c.Request.Context()。业务 handler 里直接用 c.Request.Context() 派生子 span 即可。

• 必须在 gin.Default() 后立即注册，顺序不能错
• 服务名要和 Jaeger 导出器里 semconv.ServiceNameKey.String(...) 一致，否则 UI 分组失效
• 别再自己调用 tracer.StartSpanFromContext —— 中间件已做完，重复调用会导致 Span 嵌套错误

gRPC 场景下必须显式注册拦截器，没捷径

grpc-go 默认完全不碰 context，otelgrpc 拦截器是唯一可靠方案，且必须在 grpc.Dial 或 grpc.NewServer 时注册。

• 客户端：用 grpc.WithUnaryInterceptor(otelgrpc.UnaryClientInterceptor())
• 服务端：用 grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor())
• 拦截器依赖 otel.GetTextMapPropagator().Inject，所以仍需提前设置 propagator
• 如果用了自定义 context.WithValue 键，要确认它不会覆盖 otel.SpanContextKey

跨 goroutine 和异步任务最容易漏传 context

HTTP handler 里起 goroutine 处理日志、MQ 发送或定时清理，若直接用原 ctx 或没传 context，新 goroutine 就会生成 root span，链路断裂。

立即学习“go语言免费学习笔记（深入）”；

• 启动 goroutine 前，用 trace.ContextWithSpan(ctx, span) 或 otel.ContextWithSpan(ctx, span) 显式携带
• MQ 生产者发消息前，调用 otel.GetTextMapPropagator().Inject 把 trace context 写进消息 headers 字段（如 map[string]string）
• 消费者收到后，用 otel.GetTextMapPropagator().Extract 恢复 context，再 Tracer.StartSpan
• 切记：goroutine 里 span.Finish() 必须执行，否则 Span 永远不上报

真正麻烦的从来不是初始化 tracer，而是 context 在任意跳转点（HTTP → goroutine → MQ → gRPC）中是否被完整、正确地传递下去。漏掉一次 Inject 或 Extract，Jaeger UI 就只显示半截链路——而这种断裂往往没有错误日志，只能靠人工比对 traceID 才能发现。