Jaeger客户端初始化失败：span为空或上报无数据
常见现象是调用 tracer.StartSpan() 后得到 nil，或者服务跑起来但 Jaeger UI 里完全看不到 trace。根本原因通常是 tracer 没正确初始化，或初始化时漏了关键配置。
- 必须在 main 函数早期、任何 span 创建前完成
jaeger.NewTracer()调用，且返回值要赋给全局tracer变量（不能只声明不赋值） - 采样器配置别写死
const，生产环境至少用probabilistic并设SamplingRate: 0.1，否则高并发下直接压垮 agent - Reporter 的
LocalAgentHostPort默认是"localhost:6831"，Docker 环境里 Go 服务容器通常连不到宿主机的 localhost，得改成 host.docker.internal 或实际 agent 容器名 - 如果用
http.Reporter（比如直连 collector），URL 必须带/api/traces，少这个路径会静默失败
Context 传递断裂：下游服务收不到父 span
微服务链路断掉最常见于 HTTP 调用——上游没把 span context 注入 header，下游没从 header 提取。Go 标准库 http.Client 不自动透传，必须手动做。
- 上游发请求前，用
tracer.Inject(span.Context(), opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(req.Header)) - 下游接收请求后，先
spanCtx, _ := tracer.Extract(opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(r.Header))，再用它创建 child span - 别依赖
span.Tracer().StartSpan("xxx", ext.RPCServerOption)自动识别上下文，它只对 net/http.Handler 中间件有效，自定义 handler 或 grpc 需显式传 ctx - grpc 场景直接用
otgrpc.OpenTracingServerInterceptor(tracer)和otgrpc.OpenTracingClientInterceptor(tracer)，比手写安全
关键路径识别不准：span 名称和 tag 混乱
Jaeger UI 里点开 trace 看到一堆 handleRequest 或 process，根本分不清哪个是 DB 查询、哪个是 Redis 缓存，排查效率归零。
- span 名称必须反映真实操作，例如
"db.QueryUser"、"redis.GetSession"，禁止用泛化名 - 关键业务参数加 tag：比如
span.SetTag("user_id", userID)、span.SetTag("sql", query)（注意脱敏，别打密码字段） - 错误必须显式标记：
span.SetTag("error", true)+span.LogFields(log.String("event", "error"), log.String("message", err.Error()))，否则 Jaeger 不会标红 - 避免在 defer 里 finish span——如果函数 panic，defer 不执行，span 就永远 open，拖慢整个 trace 渲染
本地开发连不上 Jaeger UI：端口、协议、网络三重卡点
本地跑 docker run -d -p 16686:16686 jaegertracing/all-in-one 后，Go 服务日志显示上报成功，但浏览器打不开 http://localhost:16686，或者 UI 里没数据。
立即学习“go语言免费学习笔记（深入）”；
- 确认容器真在运行：
docker ps | grep jaeger，端口映射是否写成-p 16686:16686（不是 6831） - Go 服务里 reporter 配置的是 UDP（默认）还是 HTTP？all-in-one 镜像默认同时监听
6831/udp（agent 协议）和14268/http（collector 协议），别混用 - Mac M1 用户注意：Docker Desktop 的
host.docker.internal在某些版本不生效，临时方案是改 host 文件，把host.docker.internal指向127.0.0.1 - 如果用 Kubernetes，别让服务直接连
jaeger-collector:14268，优先走 sidecar 模式，通过 localhost:6831 上报，减少服务间依赖
跨服务 context 透传和 span 命名规范是真正卡住排查效率的两个点，其他都是配置问题，修一次就能长期稳定。Jaeger 不会自动猜你哪段代码重要，得靠命名和 tag 显式告诉它。
