OpenTelemetry + Jaeger 是当前最可行的组合，因 OpenTelemetry Go SDK 为事实标准，兼容 Jaeger 导出，而 jaeger-client-go 已归档；需用 otelhttp、otelgrpc、otelgin 等适配器实现自动透传 context 与 span 生命周期对齐。
为什么 OpenTelemetry + Jaeger 是当前最可行的组合
Go 生态里没有开箱即用的“全链路监控平台”，硬要套用 Spring Cloud Sleuth 那套思路会踩坑。真正落地时，OpenTelemetry Go SDK 是事实标准，它不绑定后端，但默认导出格式兼容 Jaeger 和 Zipkin；而 Jaeger 的 Go client（jaeger-client-go）已归档，新项目必须用 opentelemetry-go + otlphttp 或 jaeger-thrift 导出器。
- 别再用
jaeger-client-go初始化 tracer，它不支持 context 透传的现代 Go 并发模型 -
otelhttp中间件能自动注入 HTTP 请求的 span，但需手动 wraphttp.ServeMux或 Gin/echo 的 handler - gRPC 服务必须用
otelgrpc拦截器，否则 unary/stream 调用不会生成子 span - 跨服务传递 trace context 依赖
propagation.HTTPTraceContext{}，不是靠 header 名字硬编码
如何让 Gin 服务自动记录入口、DB、下游 HTTP 调用
Gin 默认不集成任何 tracing，但通过中间件和依赖注入可以覆盖 90% 场景。关键不是“加埋点”，而是让 span 生命周期与请求生命周期对齐。
- 入口 span 用
otelgin.Middleware（来自go.opentelemetry.io/contrib/instrumentation/github.com/gin-gonic/gin/otelgin），它基于otelhttp封装，自动提取traceparentheader - DB 层若用
database/sql，需 wrapsql.Open返回的*sql.DB为otelmysql.Wrap（MySQL）或otelpostgresql.Wrap（PostgreSQL） - 调用下游 HTTP 接口时，不要直接用
http.DefaultClient，改用otelhttp.NewClient()实例，它会自动 inject trace headers - 手动创建子 span（比如耗时计算、异步任务）时，必须从
req.Context()取 parent，不能用context.Background()
常见 span 断裂场景及修复方式
链路断掉不是因为没埋点，而是 context 没透传或 span 关闭过早。典型表现是 Jaeger UI 里只看到单个服务的 span，或者父子关系错乱。
-
goroutine 启动时未传递
req.Context()：写成go doWork()而非go doWork(req.Context())→ 子 goroutine 拿不到 parent span - 使用
time.AfterFunc或timer.Reset延迟执行时，context 已 cancel → 改用time.AfterFunc包裹的函数内重新获取 span，或用otel.WithSpanFromContext显式传入 - HTTP 客户端返回 error 后直接 return，忘了调用
span.End()→ 推荐用defer span.End()开头就写上，哪怕后续 panic 也能保证结束 - gin 中间件顺序错误：自定义中间件在
otelgin.Middleware之前注册 → trace context 还没注入，你的中间件拿不到有效 span
本地开发调试时怎么快速验证链路是否通
不用等部署到 K8s 或启动全套 Jaeger，本地可用最小闭环验证：
立即学习“go语言免费学习笔记（深入）”；
- 启动
jaeger-all-in-one：docker run -d -p 6831:6831/udp -p 16686:16686 jaegertracing/all-in-one:latest - 导出器配成
otlphttp.NewExporter，endpoint 设为http://localhost:4318/v1/traces（对应 otel-collector）或直接用jaegerthrift.NewExporter发往localhost:6831 - 用
curl -H 'traceparent: 00-12345678901234567890123456789012-1234567890123456-01' http://localhost:8080/api手动注入 trace ID，观察 Jaeger UI 是否出现完整调用树 - 检查日志输出是否有
otel.sdk.traces.span相关 warning，比如 “failed to export span” —— 多半是网络不通或 endpoint 写错
真正难的不是接入，是保持 span 语义一致：同一个业务操作，在不同服务里该用哪个 span.SetName()、要不要打 span.SetAttributes()、error 时是否标记 span.SetStatus()，这些细节没人帮你校验，只能靠团队约定和 code review。
