Golang微服务如何排查调用链问题_链路追踪分析思路

排查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()) 把它塞进每条日志，才是真闭环。