Jaeger客户端初始化必须显式设置ServiceName，否则tracer为nil导致panic；HTTP请求需手动注入/提取trace context；采样策略须提前配置；span.Finish()必须显式调用且避免在goroutine中执行。
service name 必须显式设置，否则 tracer 为 nil
Jaeger 客户端初始化时，cfg.ServiceName 不是可选字段，漏设会导致 cfg.NewTracer() 返回 nil，且不报错。后续调用 opentracing.GlobalTracer().StartSpan() 就会 panic：nil pointer dereference。
常见错误包括：
- 直接用
jaeger.NewConfig()但没赋值ServiceName - 把主机名、PID 或时间戳当 service name（如
"myapp-12345"），导致服务在 Jaeger UI 中分散成多个条目 - 从环境变量读取
JAEGER_SERVICE_NAME，但启动时变量未加载（比如在initTracer()之后才os.Setenv()）
正确做法：在调用 NewTracer() 前，确保 cfg.ServiceName = "order-service"；名称应稳定、小写、无特殊字符，推荐与部署单元一致（如 Kubernetes Deployment 名）。
HTTP 请求必须手动注入/提取 trace context
Go 标准库的 http.Client 和 http.ServeMux 完全不处理追踪头，uber-trace-id 或 traceparent 不会自动透传。漏掉任一端，链路就断开。
立即学习“go语言免费学习笔记（深入）”；
客户端发请求前要注入：
err := tracer.Inject(span.Context(), opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(req.Header))
if err != nil { /* handle */ }
服务端收请求时要提取：
wireCtx, err := tracer.Extract(opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(r.Header))
if err != nil {
span = tracer.StartSpan(r.URL.Path) // 无上游时新建 root
} else {
span = tracer.StartSpan(r.URL.Path, opentracing.ChildOf(wireCtx))
}
注意：opentracing.HTTPHeaders 只是一个常量键，不是自动行为；别手写 req.Header.Set("uber-trace-id", "...")——格式错一位（比如少一个字节）Jaeger 就丢弃整个 span。
采样策略必须在创建 tracer 前配置
默认采样率是 1%，开发时几乎看不到 trace。采样器不能运行时修改，必须在 cfg.Sampler 中提前声明。
本地调试建议：
-
cfg.Sampler.Type = "const"+cfg.Sampler.Param = 1（全采）
生产环境推荐：
-
cfg.Sampler.Type = "probabilistic"+cfg.Sampler.Param = 0.01（1%） - 若使用 Jaeger Agent，改用
cfg.Sampler.Type = "remote"，由 Agent 统一决策
误配后果：设成 "const" 但 Param = 0，所有 span 都被静默丢弃；设成空字符串或未设 Type，tracer 初始化失败。
span.Finish() 必须显式调用，且不能依赖 goroutine
忘记调用 span.Finish() 是链路“消失”最隐蔽的原因——span 滞留在内存，既不上报也不超时释放（除非你额外加了带 timeout 的 wrapper）。
正确姿势：
- 紧跟
span := tracer.StartSpan(...)后立刻写defer span.Finish() - 避免在 goroutine 中启动 span 后，把
Finish()也扔进 goroutine（执行时机不可控，极易丢失） - panic 或提前 return 会跳过 defer？那就用
if defer或显式Finish()+recover()保底
特别容易踩坑的是 Gin 中间件：只调 StartSpan 但没绑定到 r.Context()，后续业务代码拿不到当前 span，自然也 finish 不了它。
