链路ID日志串联失败主因是context断链，而非日志配置问题；必须在HTTP入口中间件用私有type traceIDKey struct{}键安全注入TraceID，显式传递至goroutine、DB查询、gRPC metadata及日志，任一环节遗漏即导致链路中断。
链路 ID 日志串联失败，90% 是因为 context 在某个环节断了——不是日志库没配好，而是 traceIDKey{} 没传进 goroutine、没塞进 DB 查询、没写到 gRPC metadata 里。
HTTP 中间件里怎么安全注入 traceID
必须在最外层中间件生成并注入，不能靠 handler 自己造；否则并发下 ID 可能复用或为空。关键动作有三步：读 header、校验并兜底、写回 context 和响应头。
- 优先解析
traceparent（格式如00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01），从中取第 2 段作为trace_id；fallback 到X-Trace-ID，再 fallback 到X-Request-ID - key 必须是私有类型，比如
type traceIDKey struct{}，绝不能用"trace_id"这种字符串字面量 - 务必调用
r = r.WithContext(context.WithValue(r.Context(), traceIDKey{}, tid))，原*http.Request的 context 是只读的 - 别忘了写回响应头：
w.Header().Set("X-Trace-ID", tid)，否则网关或前端重试时无法串联
goroutine 和 DB 调用为什么总丢 traceID
Go 的 go func() {}() 不会自动继承父 goroutine 的 context，这是生产环境最常导致链路断裂的原因。
- 错误写法：
go doSomething()——doSomething内部调用req.Context().Value()拿到的是空 context - 正确写法：
go doSomething(ctx)，且函数签名必须显式接收ctx context.Context - 数据库查询必须用
db.QueryContext(ctx, ...)；gormv2+ 支持WithContext(ctx)，老版本sqlx需手动 wrap 或换客户端 - Redis、Kafka 等第三方客户端若不支持
context，必须自己封装或改用支持的驱动
zap 日志怎么稳定带上 traceID 而不漏不串
zap.Logger 和 zap.SugaredLogger 都不感知 context，直接调用 logger.Info("msg") 不可能带 trace_id。
立即学习“go语言免费学习笔记（深入）”；
- 别用全局 logger 实例打日志，每次都要从当前
ctx派生新 logger：logger.With(zap.String("trace_id", tid)).Info(...) - 推荐封装
func LoggerFromCtx(ctx context.Context) *zap.Logger，内部提取ctx.Value(traceIDKey{})并With()注入 - 如果用 OpenTelemetry，优先选
go.opentelemetry.io/contrib/instrumentation/zap提供的OTELZapCore，它会在每次Write时主动调用trace.SpanFromContext(ctx) - 注意加
zap.AddCallerSkip(1)，否则日志里显示的是封装函数名，不是业务代码行号
gRPC 客户端怎么把 traceID 透传给下游服务
HTTP 靠中间件自动注入 context，gRPC 没这层机制。只调用 context.WithValue(ctx, traceKey, tid)，下游服务的 ctx.Value(traceKey) 一定是 nil —— 因为 gRPC 的 metadata.MD 和 context.Context 是两个独立容器。
- 客户端发起调用前，用
metadata.Pairs("x-trace-id", tid)构造metadata.MD，再通过grpc.InjectMetadata(ctx, md)注入 - 更稳妥的做法是
metadata.AppendToOutgoingContext(ctx, "x-trace-id", tid)，避免覆盖已有 metadata - 服务端在
UnaryServerInterceptor中用metadata.FromIncomingContext(ctx)取头，再用context.WithValue塞回 context - header 名统一用小写
x-trace-id，gRPC metadata key 默认转为小写，大小写不一致会导致取不到
真正难的不是生成一个 ID，而是确保它从 HTTP 入口开始，穿过每一个 goroutine、每一次 DB 查询、每一条日志、每一通 gRPC 调用，全程不被覆盖、不被丢弃、不被误用。任何一环用错 key、漏传 ctx、拼错 header，链路就断了，而且很难定位是哪一环断的。
