Jaeger客户端初始化必须传入正确服务名，它是UI分组过滤核心；Context需贯穿调用链，漏传则链路断裂；Span应按业务边界合理嵌套，避免过深或过粗；开发时须直连Agent并验证连通性，否则Span静默丢失。

Jaeger客户端初始化必须传入正确的服务名

服务名不是随便起的，它是链路数据在Jaeger UI里分组和过滤的核心依据。如果多个微服务用了相同服务名，它们的Span会混在一起，根本没法区分谁是谁；如果写错了（比如带空格、下划线或大小写不一致），后端Collector可能拒绝上报，或者UI里搜不到。

• 用 os.Getenv("SERVICE_NAME") 从环境变量读取，避免硬编码
• 确保所有同名服务实例使用完全一致的服务名（注意大小写和连字符）
• 不要用包名、主机名或随机字符串代替服务名——它代表的是逻辑服务身份，不是物理标识
• 常见错误现象：400 Bad Request 上报失败，日志里出现 "invalid service name"

Context传递必须贯穿整个HTTP/gRPC调用链

Go里没有隐式上下文继承，context.Context 不会自动跨goroutine或跨网络边界传播。漏传一次，后续所有Span就断了，链路变成碎片化“孤岛”，你看到的只是半截请求。

• HTTP handler里用 tracer.Extract 从 req.Header 解析父Span，再注入到新Context中
• 发起下游HTTP请求前，用 tracer.Inject 把当前Span塞进 req.Header
• gRPC场景必须用 grpc.Dial 的 grpc.WithUnaryInterceptor + opentracing.GRPCTextMapPropagator，不能只靠手动传Context
• 容易踩的坑：defer里调用 span.Finish() 但没把带span的Context传给子goroutine，导致子goroutine新建了无父Span的root span

Span生命周期管理要匹配实际业务边界

不是每个函数都该起一个Span，也不是所有Span都该设成child。Span嵌套过深或粒度太粗，都会让瓶颈定位失真——前者拖慢性能、撑爆Jaeger存储，后者让你看不出到底是DB慢还是缓存慢。

Golang Uber Dig

使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等

下载

• 入口层（如HTTP handler）建一个 server 类型Span，用 opentracing.StartSpanFromContext
• 关键依赖调用（DB查询、Redis Get、下游gRPC）各自建独立 client Span，显式指定 opentracing.ChildOf 父Span
• 避免在for循环里反复 StartSpan，改用一个Span + 标签记录迭代次数或关键指标
• 性能影响：每个Span默认采集100%采样率时，高频小Span会导致CPU和网络开销明显上升；生产建议用 jaeger.SamplerTypeConst 配 0.01 或动态采样策略

本地开发时必须关闭采样或直连Agent避免丢Span

默认配置下，Jaeger SDK会尝试连 localhost:6831 发送UDP包。但Docker容器、WSL或防火墙常拦截这个端口，结果是Span静默丢失，你以为链路正常，其实全是黑盒。

立即学习“go语言免费学习笔记（深入）”；

• 开发阶段优先用 jaeger.NewConstSampler(true) + jaeger.NewLocalAgentReporter，并确认 agent.host-port 可达（可用 nc -u localhost 6831 测试）
• 若用All-in-One Docker版Jaeger，确保Go服务和jaeger-agent在同一个Docker网络，且host设为容器名而非localhost
• 常见错误现象：代码里 span.Log() 正常执行，但Jaeger UI里查不到任何数据，也无报错日志
• 兼容性注意：Go 1.21+ 默认启用 net/http 的 HTTP/2 支持，某些旧版Jaeger Collector不处理 HTTP/2 的trace上报，可临时加 GODEBUG=http2server=0

链路追踪真正难的不是集成，而是Context在哪断、Span在哪起、采样率怎么压——这些地方一松动，数据就不可信。别信“配完就生效”，每个服务启动后至少用curl触发一次全链路，盯着Jaeger UI看Span数量和层级是否符合预期。