排查Golang微服务调用链问题，核心是用TraceID串联上下文、Span定位耗时单元、上下游关系验证路径；TraceID断开、Span未继承或上报失败均导致链路不可见。
排查 Golang 微服务调用链问题，核心不是“看日志”，而是“用 TraceID 串联上下文、用 Span 定位耗时单元、用上下游关系验证传播路径”——只要 TraceID 断了、Span 没继承、或 exporter 上报失败，链路就不可见。
TraceID 在 HTTP 入口没透传？检查 otelhttp.NewHandler 是否包裹了 handler
很多团队手动解析 X-Trace-ID，结果和 OpenTelemetry 的 W3C traceparent 标准冲突，导致链路断裂。OTel 默认只认 traceparent，不自动兼容自定义 Header。
- 错误做法：自己写中间件从
r.Header.Get("X-Trace-ID")提取并塞进 context —— 这样 Span 没父关系，Jaeger 里显示为孤立根 Span - 正确做法：统一用
otelhttp.NewHandler包裹路由 handler，它会自动从traceparent解析上下文、创建 server span，并关联 parent - 验证方式：curl -H 'traceparent: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01' http://localhost:8080/api/order，再查 Jaeger —— 若没出现父子 Span，说明中间件没生效或被绕过（比如用了
http.ServeMux却没 wrap）
下游 HTTP 调用没链上？确认 otelhttp.NewClient 和 propagator.Inject 二选一，别混用
常见错误是既用 otelhttp.NewClient，又手动调用 propagator.Inject，导致 traceparent 被写两次，Jaeger 解析失败。
-
otelhttp.NewClient已内置 Inject 逻辑，只需直接调用client.Do(req)，无需额外处理 header - 若必须用原生
http.Client（比如要自定义 Transport），才需手动 Inject：ctx := r.Context() propagator := propagation.TraceContext{} propagator.Inject(ctx, propagation.HeaderCarrier(req.Header)) resp, _ := http.DefaultClient.Do(req) - 注意：Inject 前确保
ctx里有 active span（即 handler 中已 Start），否则注入的是空 traceparent
gRPC 调用链断在服务端？检查 grpc.UnaryServerInterceptor 是否注册且顺序正确
gRPC 拦截器未注册或注册位置不对（如放在认证拦截器之后），会导致 metadata 里的 traceparent 来不及被 OTel 提取，server span 就成了新 Trace 的起点。
立即学习“go语言免费学习笔记（深入）”；
- 必须在
grpc.Server初始化时，通过grpc.StatsHandler(otelgrpc.NewServerHandler())或grpc.UnaryInterceptor(otelgrpc.UnaryServerInterceptor())注册 - 避免拦截器顺序冲突：如果用了自定义 auth 拦截器，它不能提前 return 或 panic，否则
otelgrpc.UnaryServerInterceptor不会执行 - 客户端同理：用
grpc.WithStatsHandler(otelgrpc.NewClientHandler())，而非仅靠metadata.AppendToOutgoingContext手动传
Jaeger 看不到数据？先盯住 TracerProvider 初始化时机和采样率
上报失败往往不是网络问题，而是 SDK 根本没启动，或采样率设成 0%。
- 初始化必须在
main()早期完成，且不能被 defer 或 goroutine 延迟 —— 否则第一个请求进来时otel.Tracer返回的是 noop 实现 - 生产环境默认用
sdktrace.TraceIDRatioBased(0.01)（1% 采样），但调试时务必改成sdktrace.AlwaysSample，否则 99% 请求根本不上报 - 检查 exporter 日志：启用
otel.SetErrorHandler，若看到"failed to export spans: context deadline exceeded"，说明 Jaeger Agent 不可达或 UDP 端口（6831）被防火墙拦了
最常被忽略的一点：日志没打上 trace_id 和 span_id 字段。即使链路完整，没有结构化日志关联，你依然得靠猜去匹配哪条日志属于哪个 Span —— 用 zap.String("trace_id", span.SpanContext().TraceID().String()) 把它塞进每条日志，才是真闭环。
