TraceID必须从context.Context动态获取,不可用全局变量或初始化时固化;需定义私有key类型、在入口中间件提取并注入context、下游透传、用log.Valuer动态绑定日志字段,且HTTP/gRPC透传不能中断。

TraceID 必须从 context.Context 里取,不能靠全局变量或初始化时塞
kratos 不提供自动注入 TraceID 的 magic 功能。你看到的日志里有 trace_id,本质是靠 log.With() 绑定一个动态 Valuer 实现的——这个 Valuer 每次打日志前都会重新从当前 context.Context 中提取值。如果上下文里没 trace ID,或者你用了错误的 key 类型(比如用 string 做 key),它就为空或 panic。
常见错误现象:
- 所有日志里
trace_id=后面是空字符串或<nil></nil> - 异步 goroutine(如
go func() {}())里日志丢失 trace ID - HTTP handler 里手动 new 了个新 context,没把原 context 的 trace ID 传进去
正确做法是:
- 定义私有 key 类型:
type traceIDKey string,避免和其他库冲突 - 入口处(如 HTTP middleware 或 gRPC interceptor)从 header(
X-Trace-ID)或 metadata 提取并写入 context:ctx = context.WithValue(ctx, traceIDKey("trace_id"), tid) - 下游调用(如发 HTTP 请求、gRPC 调用)前,必须显式从 ctx 取出 trace ID 并透传到请求头或 metadata 中
用 log.With + log.Valuer 实现动态绑定
log.With() 接收的不是固定值,而是实现了 log.Valuer 接口的函数。它会在每次 Log() 被调用时执行,从而拿到当前 goroutine 的最新 context。
示例代码(注意 key 类型和取值逻辑):
type traceIDKey string
const traceIDKeyKey traceIDKey = "trace_id"
func TraceIDValuer() log.Valuer {
return func(ctx context.Context) interface{} {
if tid, ok := ctx.Value(traceIDKeyKey).(string); ok {
return tid
}
return ""
}
}
// 构建 logger 时绑定
logger := log.NewStdLogger(os.Stdout)
logger = log.With(logger,
"trace_id", TraceIDValuer(),
"span_id", SpanIDValuer(), // 同理可加
"ts", log.DefaultTimestamp,
"caller", log.DefaultCaller,
)
h := log.NewHelper(logger)
关键点:
-
TraceIDValuer()返回的是函数,不是字符串——这是动态性的核心 - 不要在初始化 logger 时用
log.With(logger, "trace_id", "xxx")直接传字符串,那会固化成启动时刻的值 - 如果你用的是 zap 等第三方日志库封装,也要确保其 wrapper 层支持从 context 动态取值,而不是只读一次
HTTP 和 gRPC 场景下 trace ID 透传不能断
kratos 的 metadata 中间件能自动把 HTTP header 映射进 context,但前提是 header 名匹配。默认它只处理 X-Request-ID,而非常见的 X-Trace-ID。
所以你得自己写 middleware 或改配置:
- HTTP 服务:在 server 初始化时注册自定义 middleware,从
X-Trace-ID提取并写入 context - gRPC 服务:用
grpc.UnaryServerInterceptor从metadata.MD中取trace-id(注意连字符格式,gRPC metadata 不支持下划线) - 客户端调用:HTTP client 发请求前,从当前 ctx 取 trace ID,加到 header;gRPC client 则加到
metadata.MD
漏掉任意一环,链路就在那个节点断裂。尤其注意:
- 异步任务(
@Async、定时任务、消息消费)必须手动把父 context 传进去,不能用context.Background() - 中间件顺序很重要:trace ID 注入 middleware 必须在日志 middleware 之前执行
Filter 和 Helper 配合做脱敏,但别影响 trace ID 输出
kratos 的 log.FilterKey("password") 会把日志中 key 为 password 的 value 替换为 ***,但它不影响 trace_id 这类全局字段——因为 trace_id 是通过 log.With() 绑定在 logger 实例上的,属于日志输出的“固定前缀”,不在 keyvals 参数里。
但要注意:
- 如果你在业务代码里手动写了
h.Infow("trace_id", tid, "msg", "hello"),那这个trace_id就进了keyvals,会被FilterKey当作普通字段处理 - 推荐统一走
log.With()绑定,业务代码只用h.Info()、h.Errorw()等,不手动传 trace_id - Filter 不该用来“补”trace_id,那是 Valuer 的事;它的作用是防止敏感字段泄露,比如用户手机号、token 字段
最易被忽略的一点:trace ID 的生成时机必须唯一且稳定。它应该由网关或最外层服务统一生成并注入,而不是每个微服务都自己生成。否则你看到的是一堆无法串联的“伪链路”。


















