Go slog ReplaceAttr 为什么会收到空分组属性

ReplaceAttr 收到空的 groups 并不是异常，也不表示 slog 创建了一个坏掉的分组。它表示当前属性位于日志记录顶层。时间、级别、消息、可选的 source 等内置属性，以及未放进 slog.Group 的普通属性，都会以空路径进入回调。

另一个关键点是：ReplaceAttr 不会收到 Group 属性本身，只会收到 Group 里面的非 Group 属性。此时 groups 才会包含从外到内的分组名。

官方文档：https://pkg.go.dev/log/slog

ReplaceAttr 收到空 groups 是正常现象

HandlerOptions.ReplaceAttr 的第一个参数是“当前打开的分组路径”，而不是“待处理的分组属性”。下面的记录包含一个顶层字段和一个名为 request 的分组：

logger.Info("finished",
    slog.String("service", "gateway"), // 顶层属性，groups 为空
    slog.Group("request",
        slog.String("method", "GET"),  // groups 为 []string{"request"}
        slog.Int("status", 200),
    ),
)

回调会依次看到内置属性、service、method 和 status。其中 request 这个 Group 容器本身不会作为 Attr 传给回调。也就是说，看到空 groups 时，先判断当前 a.Key 是不是顶层内置字段或普通字段，不要直接当成错误。

内置属性为什么也会进入回调

TextHandler 和 JSONHandler 会把记录的时间、级别、消息，以及启用 AddSource 后的源位置转换成属性，再交给 ReplaceAttr。这些属性都位于顶层，因此 groups 为空：

• slog.TimeKey：记录时间；时间为零值时省略；
• slog.LevelKey：日志级别；
• slog.MessageKey：消息文本；
• slog.SourceKey：只有 AddSource 为 true 时出现。

因此，一个只想处理业务字段的回调应先排除这些 key；一个想删除时间字段的回调，则应同时检查 len(groups) == 0，避免未来同名业务字段被误删。

replace := func(groups []string, a slog.Attr) slog.Attr {
    // 只删除顶层内置时间字段
    if len(groups) == 0 && a.Key == slog.TimeKey {
        return slog.Attr{}
    }
    return a
}

handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    ReplaceAttr: replace, // 每个非 Group 属性都会经过这里
})

空分组、空路径和零值 Attr 不是一回事

排查时最容易混淆的是下面三种“空”：

空名称 Group 不会把空字符串追加到 groups。它的子属性像直接写在当前位置一样被处理。如果一个 Group 本来有子属性，但这些子属性全部被 ReplaceAttr 删除，内置 Handler 最终也会忽略这个空 Group，不输出空对象。

按完整分组路径处理字段

规模较大的服务常见同名字段，例如顶层 id、request.id 和 user.id。只判断 a.Key 会误处理，应该把 groups 路径和 key 一起判断。

func sameGroups(groups []string, want ...string) bool {
    if len(groups) != len(want) {
        return false // 路径层级不同，不是目标字段
    }
    for i := range groups {
        if groups[i] != want[i] {
            return false
        }
    }
    return true
}

func replaceAttr(groups []string, a slog.Attr) slog.Attr {
    // 删除顶层时间，保留分组内可能同名的业务字段
    if len(groups) == 0 && a.Key == slog.TimeKey {
        return slog.Attr{}
    }

    // 只对 user.credentials.token 做脱敏
    if sameGroups(groups, "user", "credentials") && a.Key == "token" {
        a.Value = slog.StringValue("[REDACTED]")
        return a
    }

    // 把 request.latency 的 duration 转成毫秒整数
    if sameGroups(groups, "request") && a.Key == "latency" {
        a.Value = slog.Int64Value(a.Value.Duration().Milliseconds())
    }
    return a
}

官方约定还指出，传入的 groups 切片不能被保留或修改。内置 Handler 为了减少分配会复用内部切片；如果需要异步统计路径，应在回调中复制内容，而不是把原切片保存到全局变量。

func copyPath(groups []string) []string {
    // 显式复制，避免持有 Handler 可复用的内部切片
    return append([]string(nil), groups...)
}

为什么偶尔会看到零值 Attr

内置 Handler 会对每个非 Group Attr 调用 ReplaceAttr，然后再检查返回值是否为空。如果业务代码显式把 slog.Attr{} 放进 Record，回调可能先看到这个零值；如果回调自己返回零值，Handler 会把属性丢弃。

这和“空 groups”是两件事。判断零值属性可以使用 a.Equal(slog.Attr{})，不要只用 a.Key == ""，因为空 key 的非空属性仍然可能来自业务代码，而空 key 的 Group 还具有内联语义。

func replaceAttr(groups []string, a slog.Attr) slog.Attr {
    // 零值 Attr 没有可转换内容，原样返回后 Handler 会忽略
    if a.Equal(slog.Attr{}) {
        return a
    }

    // 空 key 不自动等于零值，仍需查看 Value
    if a.Key == "" {
        return a
    }
    return a
}

高吞吐日志场景的实现取舍

ReplaceAttr 位于每条已启用日志的属性处理路径上。服务每秒输出大量日志时，字符串拼接、正则表达式、反射或创建临时 map 都会放大成本。建议把规则保持为有限的 key 比较和短路径判断：

• 先用 len(groups) 和 a.Key 做廉价过滤；
• 只对确定的字段调用 a.Value.Time()、Duration() 等类型方法；
• 不要在回调里使用同一个 slog Logger 打印调试日志，避免再次进入 ReplaceAttr；
• 临时排查可用独立的 fmt.Fprintf(os.Stderr, ...)，上线前移除；
• 需要统计时使用并发安全计数器，不要持有传入的 groups 切片。

var topLevel atomic.Uint64

replace := func(groups []string, a slog.Attr) slog.Attr {
    if len(groups) == 0 {
        topLevel.Add(1) // 只做常数时间计数，不在回调里递归写 slog
    }
    return a
}

排错清单

1. 先确认“空”指的是 groups 长度为零，还是 a.Equal(slog.Attr{})。
2. 打印 key 时考虑内置的 time、level、msg 和 source。
3. 不要期待收到 Group 容器；观察其子属性和 groups 路径。
4. 空名称 Group 会内联，不会生成空路径段。
5. 返回零值 Attr 会删除字段；一个 Group 的子字段全被删除后，Group 也会消失。
6. 不要修改或长期保存 groups；需要保存时先复制。

常见问题

为什么第一批回调的 groups 都是空的？

Handler 会先处理顶层内置属性，然后处理顶层业务属性。这些属性没有父 Group，所以 groups 为空。只有进入命名 Group 的子属性后才会看到路径内容。

ReplaceAttr 能直接重命名 Group 吗？

不能。官方约定是 ReplaceAttr 不接收 Group 属性本身，只接收其内容。需要重命名分组时，应在创建日志字段或包装 Handler 的 WithGroup 行为处处理。

返回 slog.Attr{} 会发生什么？

该属性被丢弃。如果一个 Group 的所有子属性都被丢弃，内置 TextHandler 和 JSONHandler 也不会输出空 Group。

groups 可以直接 append 后保存吗？

不要修改或持有传入切片。需要保存路径时先复制，例如 append([]string(nil), groups...)。