把 trace 标识贯穿日志上下文但不污染业务函数

我第一次给一个 Go 服务补链路标识时，最直觉的写法是在每个业务函数里多传一个 traceID string，然后每次记录日志都手动追加 "trace_id", traceID。这很快能工作，但几周后，业务签名、日志字段和调用链绑在了一起：有人漏传，有人改了字段名，还有人把客户端传来的值原样当成可信标识。

更稳妥的做法是：请求边界负责产生或接收可信 trace 标识，context.Context 负责随调用链携带它，slog.Handler 在日志出口统一把它写入记录。业务函数只使用本来就应该传递的 ctx，调用 InfoContext、ErrorContext 等方法，不需要认识日志元数据。

官方资料：https://pkg.go.dev/log/slog

Context 文档：https://pkg.go.dev/context

先界定要保护的日志关联资产

trace 标识看起来只是一个字符串，但在排障系统里，它至少关联四类资产：

• 关联完整性：同一请求产生的日志应落在同一个 trace_id 下，不能被调用方随意改写。
• 业务接口纯度：订单、库存、计费等函数不应为了日志而新增 traceID 参数。
• 日志字段一致性：所有组件使用固定键名和格式，检索条件才不会碎片化。
• 隐私边界：trace_id 只用于关联，不应顺手把令牌、Cookie、用户输入或完整请求体带入日志。

log/slog 官方文档明确提供了带 Context 的输出方法，并指出 Handler 可以从调用点的 Context 中加入信息，例如当前 span 的标识。它还要求 Handler 修改 slog.Record 前先克隆记录，避免共享状态带来意外影响。这正好给了我们一个集中控制点。

识别最容易踩中的五条风险路径

我后来把这件事当成一个小型威胁模型处理，排查速度反而更快。这里的“威胁”不只指攻击，也包括会破坏日志可信度的工程错误。

这里还有一个常见误区：trace_id 不是身份凭证。即使它来自受信任的追踪系统，也不能代替用户鉴权、请求签名或权限判断。它只回答“这些日志是否属于同一条观测链路”。

用 Handler 在日志出口集中注入 trace_id

下面的包装器把“从 Context 读取 trace_id”和“把字段写入日志记录”都放进 Handler。提取逻辑通过函数注入，后面接自建标识或 OpenTelemetry 都不用改业务代码。

package observability

import (
    "context"
    "log/slog"
)

// TraceIDFunc 只负责从上下文读取可信的链路标识。
type TraceIDFunc func(context.Context) (string, bool)

// TraceHandler 在日志出口统一追加 trace_id。
type TraceHandler struct {
    next    slog.Handler
    traceID TraceIDFunc
}

func NewTraceHandler(next slog.Handler, traceID TraceIDFunc) *TraceHandler {
    return &TraceHandler{next: next, traceID: traceID}
}

func (h *TraceHandler) Enabled(ctx context.Context, level slog.Level) bool {
    // 级别判断完全交给底层 Handler，避免改变原有过滤规则。
    return h.next.Enabled(ctx, level)
}

func (h *TraceHandler) Handle(ctx context.Context, record slog.Record) error {
    id, ok := h.traceID(ctx)
    if ok && id != "" {
        // slog.Record 可能共享内部状态，修改前先克隆。
        record = record.Clone()
        record.AddAttrs(slog.String("trace_id", id))
    }
    return h.next.Handle(ctx, record)
}

func (h *TraceHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
    // 包装器必须跟随底层 Handler 派生，保留预绑定字段。
    return &TraceHandler{
        next:    h.next.WithAttrs(attrs),
        traceID: h.traceID,
    }
}

func (h *TraceHandler) WithGroup(name string) slog.Handler {
    // 分组只改变底层字段命名空间，不丢失 trace 提取器。
    return &TraceHandler{
        next:    h.next.WithGroup(name),
        traceID: h.traceID,
    }
}

WithAttrs 和 WithGroup 不是可有可无的样板。Logger.With、Logger.WithGroup 会调用它们生成新的 Handler；如果包装器直接返回底层 Handler，后续日志就会悄悄绕过 trace 注入。

业务服务只需要持有普通 Logger，并把已有 Context 交给日志调用：

type OrderService struct {
    logger *slog.Logger
}

func (s *OrderService) Confirm(ctx context.Context, orderID string) error {
    // 业务只描述事件，trace_id 由 Handler 从 ctx 自动补充。
    s.logger.InfoContext(ctx, "confirming order",
        slog.String("order_id", orderID),
    )

    if err := confirmOrder(ctx, orderID); err != nil {
        // 错误日志沿用同一个 ctx，因此仍能与请求链关联。
        s.logger.ErrorContext(ctx, "confirm order failed",
            slog.String("order_id", orderID),
            slog.Any("error", err),
        )
        return err
    }
    return nil
}

这就是“不污染业务函数”的实际含义：函数仍然为了取消、超时和请求作用域接收 Context，日志只消费这条已有通道，不再增加 traceID 参数，也不让每个调用点重复约定字段名。

在 HTTP 边界创建可信 trace 标识

如果还没有分布式追踪系统，可以先在 HTTP 中间件里管理应用级 trace_id。下面示例允许复用格式合格的上游标识，否则生成新的随机值。生产环境还应结合网关信任边界决定是否接受外部请求头。

package requesttrace

import (
    "context"
    "crypto/rand"
    "encoding/hex"
    "net/http"
    "regexp"
)

type contextKey struct{}

var safeTraceID = regexp.MustCompile(`^[a-f0-9]{32}$`)

func WithTraceID(ctx context.Context, id string) context.Context {
    // 使用私有键类型，避免与其他包的 Context 键冲突。
    return context.WithValue(ctx, contextKey{}, id)
}

func TraceIDFromContext(ctx context.Context) (string, bool) {
    id, ok := ctx.Value(contextKey{}).(string)
    return id, ok && safeTraceID.MatchString(id)
}

func newTraceID() string {
    var b [16]byte
    if _, err := rand.Read(b[:]); err != nil {
        // 随机源失败属于启动或基础设施异常，应交给上层决定如何终止请求。
        panic("secure random source unavailable")
    }
    return hex.EncodeToString(b[:])
}

func Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Trace-ID")
        if !safeTraceID.MatchString(id) {
            // 不可信或不合格的外部值一律替换，防止日志注入和超长字段。
            id = newTraceID()
        }

        ctx := WithTraceID(r.Context(), id)
        w.Header().Set("X-Trace-ID", id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

Logger 的装配集中在程序入口：

base := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level: slog.LevelInfo, // 生产环境默认记录 Info 及以上级别。
})

handler := observability.NewTraceHandler(
    base,
    requesttrace.TraceIDFromContext,
)
logger := slog.New(handler)

// 服务只接收普通 Logger，不感知 trace_id 的存储方式。
service := &OrderService{logger: logger}

没有 trace_id 时，Handler 直接转交原记录，不建议写入空字符串。这样查询时可以区分“链路标识确实缺失”和“标识存在但值为空”。如果你需要监控缺失率，可以在 Handler 内增加独立的 trace_missing=true，但不要把它和业务失败混为一谈。

接入 OpenTelemetry 时只替换提取器

使用 OpenTelemetry 后，不要再维护第二套 trace_id。SpanContext 已经通过 Context 传播时，只需把提取器换成官方 trace 包提供的读取方式。业务服务与 TraceHandler 都不用改。

OpenTelemetry Trace API：https://pkg.go.dev/go.opentelemetry.io/otel/trace

import (
    "context"

    oteltrace "go.opentelemetry.io/otel/trace"
)

func OTelTraceID(ctx context.Context) (string, bool) {
    spanContext := oteltrace.SpanContextFromContext(ctx)
    if !spanContext.IsValid() {
        // 无有效 SpanContext 时不写伪造或全零的 trace_id。
        return "", false
    }
    return spanContext.TraceID().String(), true
}

需要注意，是否接受远端 SpanContext 是传播器和入口中间件的职责；日志 Handler 只读取已经建立的上下文，不在输出阶段决定信任。把信任判断放在入口、把字段注入放在出口，两个边界各做一件事，后续替换追踪供应商也更轻。

用审计字段和检查清单收口

我现在会在合并前用下面这份清单快速过一遍。它不依赖某个日志平台，也不要求业务函数知道 trace 的实现：

• 所有请求级日志是否使用 DebugContext、InfoContext、WarnContext 或 ErrorContext？
• trace_id 是否只由入口中间件和 Handler 管理，业务调用点不再重复写入？
• 包装 Handler 是否完整转发 Enabled、WithAttrs、WithGroup？
• 修改 slog.Record 前是否调用了 Clone？
• 外部请求头是否有长度、字符集和信任来源限制？
• Context 中是否只保存请求级小值，没有塞 Logger、请求体或可变业务对象？
• 日志系统是否把 trace_id 作为精确匹配字段，而不是全文分词字段？

几个容易追问的边界

可以直接把 Logger 放进 Context 吗？

能实现，但通常不值得。Logger 是依赖，适合通过结构体字段或显式参数注入；Context 更适合请求截止时间、取消信号和跨 API 边界的请求级数据。把 Logger 放进去会隐藏依赖，也不利于测试和替换。

为什么不用 logger.With("trace_id", id)？

在请求入口创建一个带固定 trace_id 的子 Logger 是可行方案，而且对单个请求内反复记录同一属性很直观。但这要求你继续把这个 Logger 传入业务层，或者把它塞进 Context。Handler 方案更适合“业务层已经传 ctx、希望日志依赖保持显式”的工程。两者没有绝对优劣，关键是不要同时使用而产生重复键。

后台任务没有 HTTP 请求怎么办？

在任务消费边界创建或恢复 trace 标识，再放入任务 Context，模式和 HTTP 中间件相同。若任务本来没有链路，就让字段缺失，不要为了日志整齐生成一个无法关联任何上游的假标识。

是否应该记录 span_id？

如果一条 trace 内有多个并发或嵌套 span，增加 span_id 能把日志定位到更细的操作。仍建议在同一个 Handler 中从 SpanContext 一次提取，并保持固定字段名。

最终的判断很简单：trace 标识属于请求观测上下文，不属于业务参数。让入口建立可信上下文，让 slog Handler 在出口消费它，业务函数只保留自己的领域职责。这套结构不追求“完全没有 Context”，而是让 Context 只承担它本来就擅长的跨边界传播。