Jaeger Agent 启动失败因未配Collector或端口不匹配，应直连Collector或用all-in-one镜像；Go SDK需显式设非空service name；OTLP需配支持OTLP的Collector；跨goroutine须手动传递span context。
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镜像，并启用otlpreceiver 和jaegerexporter（复用原有 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。
