jaeger tracer 初始化必须设 servicename 且 reporter 端口匹配，否则 cfg.newtracer() 静默返回 nil 导致后续 panic；echo 中间件需显式绑定 span 到 request.context；跨协议调用须手动注入/提取 spancontext；tag/log 禁用指针和 nil，采样率应使用 remote 动态下发。
tracer 初始化必须设 ServiceName 且 reporter 端口匹配
不填 ServiceName 或错配 reporter.LocalAgentHostPort，cfg.NewTracer() 会静默返回 nil，后续调用 tracer.StartSpan() 直接 panic——但错误堆栈里不提示初始化失败，只报空指针，排查极耗时。
本地开发最稳组合是：LocalAgentHostPort: "localhost:6831"（UDP，Thrift Compact 协议），对应 jaegertracing/all-in-one 默认监听端口。Mac 上 Docker Desktop 的 UDP 转发偶有失效，可改用 --network=host 启动 agent，让 Go 进程直连 localhost:6831。
若误配成 "localhost:6832"（Binary 协议端口），span 数据会被静默丢弃，无日志、无报错、UI 空白——这是本地调试最常踩的坑。
Echo 中间件必须显式绑定 span 到 echo.Context 和 http.Request.Context()
只调 tracer.StartSpan("http-server") 不够。生成的 span 必须注入到 http.Request.Context()，否则下游业务 handler 或其他中间件（如日志、鉴权）无法派生子 span，链路在第一跳就断裂。
正确做法分三步：
- 从请求 header 提取上游 context：
tracer.Extract(opentracing.HTTPHeaders, opentracing.HTTPHeadersCarrier(r.Request.Header))，失败时才新建 root span - 用
opentracing.ContextWithSpan(r.Request.Context(), span)构造新 context - 调
r.SetRequest(r.Request.WithContext(newCtx))把 span 绑定进 echo 请求上下文
别在 defer span.Finish() 前修改 w.Header() 或写 response body，某些中间件（如 CORS、gzip）会提前关闭 writer 导致 panic。
Echo框架 5.1.0 版本源码包下载，适合关注 RealIP 行为变化、StartConfig.Listener、NewDefaultFS 和观测性中间件入口的开发团队。
跨协议调用（gRPC/MQ）必须手动注入/提取 SpanContext
HTTP header 自动带 uber-trace-id，但 gRPC 的 metadata、Kafka 消息头、Redis Pub/Sub payload 完全不识别它——不显式操作，链路就在第一个非 HTTP 跳断开。
gRPC 场景下：
- 客户端：用
opentracing.GlobalTracer().Inject(span.Context(), opentracing.TextMap, opentracing.TextMapCarrier(md))注入到metadata.MD - 服务端：用
opentracing.GlobalTracer().Extract(opentracing.TextMap, opentracing.TextMapCarrier(md))提取 context
MQ 类场景同理，需把 span.Context() 序列化后写入消息头（如 Kafka headers 或 RabbitMQ message properties），消费端再反向提取。漏掉任意一端，跨服务链路即中断。
Tag 和 Log 值禁用指针和 nil，采样率别在生产硬编码为 1.0
往 span 打 tag 或 log 时传 *string、nil 或未解引用的指针，Jaeger client 会 panic 或静默丢弃该 span——尤其常见于结构体字段未判空直接 span.SetTag("user_id", user.ID)，而 user 是 nil。
生产环境别开 LogSpans: true，它会让每个 span 同步打日志，性能开销极大。改用 BufferFlushInterval: 1 * time.Second 控制批量上报节奏。
采样率建议用 sampler.type=remote（默认），由 Jaeger Agent 动态下发；硬编码 sampler.param=1.0 在高流量服务上极易压垮 Collector 和存储后端。
