Go 分布式追踪 Jaeger 实战搭建指南

本文深入剖析了在 Go 微服务中落地 Jaeger 分布式追踪的典型实战痛点与精准解法：从 Jaeger Agent 启动失败（connection refused）的根本原因——UDP 端口未暴露或 Collector 配置错位，到必须显式设置非空 service name 才能在 UI 中正确归类；从 OTLP 迁移时因协议/端口不匹配导致的 span 丢失，到跨 goroutine 场景下 context 传播断裂引发的链路断开；覆盖直连 Collector、all-in-one 快速启动、OpenTelemetry 平滑迁移及上下文手动传递等关键路径，每一步都直击生产环境高频踩坑点，助你构建真正可靠、可观测的分布式追踪能力。

Jaeger Agent 启动失败，提示 connection refused

常见于本地开发环境直接启动 jaeger-agent 但没配对后端（Collector），或 Collector 未监听 UDP 端口。Jaeger Agent 默认通过 UDP 向 localhost:6831（compact protocol）或 localhost:6832（binary protocol）上报 span，而 Collector 默认不监听这些端口——它只暴露 gRPC/HTTP 接口（如 14250、14268）。

解决办法：跳过 Agent，让 Go 应用直连 Collector；或改用 jaeger-all-in-one 一键镜像（它自动打通 Agent → Collector → UI）：

docker run -d --name jaeger \
  -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
  -p 5775:5775/udp \
  -p 6831:6831/udp \
  -p 6832:6832/udp \
  -p 5778:5778 \
  -p 16686:16686 \
  -p 14250:14250 \
  -p 14268:14268 \
  -p 14269:14269 \
  -p 9411:9411 \
  jaegertracing/all-in-one:1.49

注意：6831/udp 必须暴露，否则 Go SDK 的默认 reporter 会静默丢 span。

Go 用 jaeger-client-go 上报 span，但 UI 里看不到服务名

根本原因是 tracer 初始化时没传 service name，或传了空字符串。Jaeger UI 按 service name 分组展示，空名会被归到 unknown_service，极难定位。

初始化必须显式指定非空 service name，且建议与你的二进制名或部署单元一致：

tracer, closer := jaeger.NewTracer(
  "my-api-service", // ← 必须非空
  jaeger.NewConstSampler(true),
  jaeger.NewRemoteReporter(jaeger.RemoteReporterParams{
    LocalAgentHostPort: "localhost:6831",
  }),
)

其他易错点：

• LocalAgentHostPort 写成 localhost:6832（binary 协议）但 Agent 实际监听的是 6831（compact），导致无报错但无数据
• 应用启停太快，closer.Close() 没调用，最后几个 span 被丢弃
• 没设 TracerOptions.EnableZipkin，但想兼容 Zipkin 格式（其实一般不需要）

迁移到 OpenTelemetry Go SDK 后 span 丢失，日志显示 failed to export trace: rpc error: code = Unavailable desc = connection closed

这是 OTLP exporter 连不上 Collector 的典型表现。OpenTelemetry Go 默认走 gRPC 协议（端口 4317），不是 Jaeger 的 6831 或 14250。你不能把旧的 Jaeger Collector 配置直接塞进 otlphttp.NewClient 或 otlpgrpc.NewClient。

正确做法分两步：

• 启动支持 OTLP 的 Collector：用官方 otel/opentelemetry-collector-contrib 镜像，并启用 otlp receiver 和 jaeger exporter（复用原有 Jaeger 后端）
• Go 代码中配置 OTLP gRPC exporter，指向 Collector 的 4317 端口

Collector 配置示例（config.yaml）：

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  jaeger:
    endpoint: "jaeger:14250"
    tls:
      insecure: true

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [jaeger]

Go 初始化片段：

exp, err := otlpgrpc.NewClient(otlpgrpc.WithInsecure(), otlpgrpc.WithEndpoint("localhost:4317"))
if err != nil {
  log.Fatal(err)
}
tp := sdktrace.NewTracerProvider(
  sdktrace.WithBatcher(exp),
  sdktrace.WithResource(resource.MustNewSchemaless(
    semconv.ServiceNameKey.String("my-api-service"),
  )),
)

注意：semconv.ServiceNameKey 是 OpenTelemetry v1.20+ 的写法，老版本用 attribute.String("service.name", ...)。

Span 上下文跨 goroutine 丢失，HTTP handler 里能打点，但异步任务里全是 nil span

Go 的 context 本身不跨 goroutine 自动传播，trace.SpanFromContext(ctx) 在新 goroutine 里拿不到父 span，除非你手动把 context 传进去。

最简方案：用 trace.ContextWithSpan 包一层再传给 goroutine：

parentCtx := r.Context()
span := trace.SpanFromContext(parentCtx)
go func(ctx context.Context) {
  // ctx 已携带 span，后续 StartSpan 会自动作为 child
  _, span := tracer.Start(ctx, "async-task")
  defer span.End()
}(trace.ContextWithSpan(parentCtx, span))

更稳妥的做法是统一用 trace.SpanContextFromContext + trace.SpanContextToContext，尤其在 channel、worker pool 等复杂调度场景下；否则看似打了点，实际链路断裂，parent_id 全是 0000000000000000。

另一个隐藏坑：http.Server 的 Handler 默认不注入 tracing context，得靠中间件（如 otelhttp.NewMiddleware）或手动 wrap r.WithContext，否则 r.Context() 从一开始就没 span。

以上就是《Go 分布式追踪 Jaeger 实战搭建指南》的详细内容，更多关于的资料请关注golang学习网公众号！