go-zero traceId 链路追踪与跨 RPC 传递

一个 traceId、一串 spanId 的长相

traceId 是 32 位十六进制（如 4bf92f3577b34da6a3ce929d0e0e4736），spanId 是 16 位。一次「网关→用户服务→订单服务」的调用，3 个 span 的 traceId 完全相同，spanId 各不相同，parent 指向上游——这就是「一条链路」。

三件套

数据去哪了

go-zero 只负责生成 span 并导出，不负责存储和展示。Span 通过 OTLP（或 Zipkin）协议异步发到 Collector（Jaeger / Tempo / Zipkin / 阿里云 SLS 等），你在那边的 UI 里按 traceId 查整条链路。所以 go-zero 这侧是「无状态的生产者」。

① config 结构（goctl 生成的已经带了）

internal/config/config.go 里内嵌的 rest.RestConf / zrpc.RpcConf 已经包含 Trace trace.Config 字段，无需手加。

② etc 配置文件填写

# user-api.yaml / user-rpc.yaml
Name: user-api
Host: 0.0.0.0
Port: 8888

Trace:
  Name: user-api            # 本服务在链路里显示的名字
  Endpoint: http://jaeger:4318/v1/traces   # OTLP HTTP 地址（或 Zipkin :14268/api/traces）
  Sampler: 1.0           # 采样率 0~1，1.0 = 全采；生产可 0.1 降成本
  Batcher: otlp          # otlp 或 zipkin，决定用哪个导出协议
  ServiceName: user-api  # 可选，覆盖 Name

入口（服务端）

go-zero 的 HTTP tracing 中间件在请求进来时：① 尝试从请求头 traceparent（W3C 标准）或兼容头里抽取上游 traceId；② 抽不到就新生成一个 traceId 并起一个 server span；③ 把这个 traceId 写进响应头 x-trace-id，所以前端/客户端能在响应里直接看到它，方便反馈给客服排查。

出口（客户端，调别的服务）

你用 go-zero 自带的 httpc 调外部 HTTP 服务时，它内部也有 tracing 拦截器：自动把当前 ctx 里的 span 上下文注入到请求头 traceparent，对端如果是 go-zero 就能抽出来接上。只要你是 l.svcCtx.PayHttp.Do(l.ctx, ...) 这种带着 ctx 调，就自动透传。

客户端（发起 RPC 的那一侧，如 API 网关）

// 你写的 logic 里，调用内部 RPC —— 注意用的是 l.ctx
func (l *CreateOrderLogic) CreateOrder(req *types.Req) (*types.Resp, error) {
    // l.ctx 已经带着上游(HTTP 入口)的 span 上下文
    user, err := l.svcCtx.UserRpc.GetUser(l.ctx, &user.GetUserReq{Id: req.Uid})
    if err != nil { return nil, err }
    // ↓ zrpc 客户端拦截器在背后做了：
    //   md := metadata.MD{}
    //   trace.Inject(l.ctx, &md)   // 把 span 上下文写进 metadata
    //   带着 md 发起 gRPC 调用
    ...
}

服务端（被调用的内部服务，如 user-rpc）

// user-rpc 的 .proto 生成后，你只需填 logic
func (s *UserServer) GetUser(ctx context.Context, req *GetUserReq) (*GetUserResp, error) {
    // zrpc 服务端拦截器在背后做了：
    //   md, _ := metadata.FromIncomingContext(ctx)
    //   parentCtx := trace.Extract(md)       // 从 metadata 抽出上游 traceId
    //   ctx = trace.StartServerSpan(parentCtx, ...)  // 起 child span
    // 于是这里 ctx 的 traceId 和网关那次请求完全相同
    u, err := s.svcCtx.UserModel.FindOne(ctx, req.Id)  // DB 调用也带同一 ctx
    ...
}

为什么不是「手动把 traceId 当 RPC 参数传」

理论上你也能在每个 .proto 里加个 trace_id 字段手动传，但那是反面模式：① 污染业务协议；② 漏传一个方法就断链；③ span 之间的父子关系（耗时、层级）全得自己维护。go-zero 用 metadata（gRPC 专用、不进业务字段） + 拦截器（自动、全覆盖） 解决了这三点，所以是标准做法。

① 日志自动带上 trace（最常用）

// 用 logx.WithContext(ctx)，日志会自动多一个 trace 字段
logx.WithContext(l.ctx).Infof("收到订单创建请求 uid=%d", req.Uid)
// 输出示例: {"@t":"...","trace":"4bf92f...","msg":"收到订单创建请求 uid=12"}

② 直接取 traceId 字符串

// 取当前 ctx 的 traceId，可用于返回给前端 / 写库 / 关联业务
tid := trace.TraceIDFromContext(l.ctx)
resp.TraceId = tid   // 返回给调用方，方便用户反馈时带上

③ 自定义 span / 给 span 打标签

// 需要给某段逻辑单独起 span 并打业务标签时
ctx, span := trace.Start(l.ctx, "business:deduct")
defer span.End()
span.SetAttributes(attribute.String("order_id", orderId))