应使用 opentelemetry 替代已归档的 jaeger-client-go，通过 otel + jaegerexporter 三步初始化 tracerprovider、配置 agent/collector exporter 并正确传入请求上下文，避免 span 断链或丢失。
Jaeger 在 Go 项目里能用，但直接集成 jaeger-client-go 已不推荐——它已归档，OpenTelemetry 才是当前稳定路径。
为什么 jaeger-client-go 不该再用
官方仓库（github.com/uber/jaeger-client-go）已于 2024 年底归档，不再接收 PR 或修复安全问题。所有新项目应迁移到 OpenTelemetry 官方 SDK，它原生支持 Jaeger 后端，且兼容性、维护性和扩展性都更强。
- 归档后
go get仍能拉取，但go.sum中的校验和可能失效，CI 构建会失败 - 其
opentracing接口已被 OpenTelemetry 的otel.Tracer取代，混用会导致上下文丢失 - 新版 Jaeger Query UI（v1.30+）对旧格式 Span 的解析支持变弱，部分字段显示为空
Go 项目接入 Jaeger 的标准做法：用 otel + jaegerexporter
核心是三步：初始化全局 TracerProvider → 创建 Exporter 指向 Jaeger Agent 或 Collector → 在 HTTP handler 或业务逻辑中打点。
- 依赖只加两个：
go.opentelemetry.io/otel和go.opentelemetry.io/otel/exporters/jaeger - Exporter 初始化时优先用
jaeger.WithAgentEndpoint()（UDP，轻量），而非WithCollectorEndpoint()（HTTP，需额外鉴权配置） - 必须调用
tp.Shutdown(context.Background())，否则进程退出前 Span 会丢失 - 不要手动调用
otel.SetTracerProvider(tp)后又在中间件里重复otel.GetTracer()—— 全局一次初始化即可
示例片段：
func initTracer() (func(context.Context) error, error) {
exporter, err := jaeger.New(jaeger.WithAgentEndpoint(
jaeger.WithAgentHost("localhost"),
jaeger.WithAgentPort("6831"),
))
if err != nil {
return nil, err
}
tp := trace.NewTracerProvider(
trace.WithBatcher(exporter),
trace.WithResource(resource.NewWithAttributes(
semconv.SchemaURL,
semconv.ServiceNameKey.String("my-api"),
)),
)
otel.SetTracerProvider(tp)
return tp.Shutdown, nil
}
Gin / Echo / HTTP 中间件里怎么传上下文
关键不是“怎么创建 Span”，而是“怎么把上游传来的 TraceID 续上”。OpenTelemetry 提供了标准的 HTTP propagator，别自己解析 X-B3-TraceId 或 uber-trace-id。
- 使用
otelhttp.NewHandler包裹你的http.Handler，它自动完成 Extract → StartSpan → Inject 全流程 - 对 Gin，用
otelgin.Middleware（来自go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin），它比手写中间件少 8 行易错代码 - 若需自定义 Span 标签（如用户 ID、订单号），在 handler 内用
span := trace.SpanFromContext(c.Request.Context())获取，再调span.SetAttributes() - 切忌在 middleware 里调
span.End()——otelhttp或otelgin已处理，重复调用会导致 panic
本地开发时 Jaeger 启动命令要配对
Docker 启动的 Jaeger 必须和 Go 端 Exporter 配置一致，否则 Span 一发就丢，UI 里查不到任何数据。
- Agent 模式（推荐）：Docker 命令带
-p 6831:6831/udp，Go 端用WithAgentEndpoint - Collector 模式（调试用）：Docker 命令加
-p 14250:14250（gRPC）或-p 14268:14268（HTTP），Go 端对应用WithCollectorEndpoint - 别用
all-in-one:latest镜像跑生产 —— 它默认只监听localhost，容器内网络不通；改用jaegertracing/all-in-one:1.49并加--collector.grpc-server.host-port=:14250 - 启动后 curl
http://localhost:16686/api/services返回空数组？说明 Exporter 没连上，先检查端口和防火墙
最常被忽略的是：Span 的生命周期必须严格匹配请求生命周期。中间件里没传 c.Request.Context() 到下游，或者 defer 调用位置错了，都会导致 Trace 断链 —— 这类问题不会报错，只会让 UI 显示“单个孤 Span”。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
