使用Golang Log/Slog结构化日志包_Go 1.21日志新标准实战

1次阅读

slog 默认无时间戳和文件行号是因设计上“显式优于隐式”,需手动启用addsource;time字段自动添加但不可定制格式;withgroup创建嵌套命名空间,with用于扁平键值;自定义handler须实现enabled、withattrs、withgroup三方法。

使用Golang Log/Slog结构化日志包_Go 1.21日志新标准实战

为什么 slog 默认输出没有时间戳和文件行号

因为 slog.NewTextHandlerslog.NewjsonHandler 默认不开启额外上下文字段,timesource(文件+行号)这些都得手动加。不是 bug,是设计上「显式优于隐式」——避免默认开销影响性能。

实操建议:

  • slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{AddSource: true, Level: slog.LevelInfo}) 启用源码位置
  • 时间戳不用手动加:只要 Handler 支持(TextHandler/JSONHandler 都支持),它会自动写入 time 字段;但格式不可定制,想改格式得自己实现 slog.Handler
  • 注意 AddSource 在生产环境可能有轻微性能损耗(需 runtime.Caller),上线前建议压测对比

slog.Withslog.WithGroup 什么时候该用哪个

With 是加扁平键值对,WithGroup 是建嵌套命名空间——不是语义区别,是结构差异。比如调试 http 请求时,把请求头、参数、响应状态全塞进一个 group,比全打平更易过滤和解析。

常见错误现象:日志里一 user_idreq_idstatus_code 平铺,查问题时分不清哪些属于同一请求上下文。

实操建议:

  • WithGroup("http") 包住一次请求的完整生命周期日志,后续所有 Info/Error 都自动带上 http.user_idhttp.status_code 这类路径前缀
  • With 适合临时上下文(如当前 goroutine 的 trace_id),WithGroup 适合有明确边界、可复用的逻辑单元(auth、db、cache)
  • JSON 输出下,group 会生成嵌套对象;Text 输出则用点号连接键名(http.status_code),别指望 Text 日志能直接解析出层级

自定义 slog.Handler 时最容易漏掉的三个方法

写个自己的 Handler 不只是实现 Handle 方法就行。EnabledWithAttrsWithGroup 这仨没处理好,会导致日志被静默丢弃、属性丢失或 group 失效——而且很难 debug,因为没报错,只是“没打出想要的字段”。

使用场景:对接内部日志平台,需要把 slog 日志转成特定 protobuf 结构,或加统一 trace 上下文。

实操建议:

  • Enabled 必须判断 level,否则 slog.Debug 在 prod 环境也可能执行(即使没输出)
  • WithAttrs 要返回新 Handler 实例,不能原地修改,否则并发写日志会 panic
  • WithGroup 如果不实现,调用方的 WithGroup 就完全失效,所有属性都变平级——这是最常被忽略的点

log 迁移到 slogPrintf-风格日志怎么处理

老代码里满屏 log.printf("user %s login failed: %v", uid, err),直接替换成 slog.Info("user login failed", "user_id", uid, "err", err) 很啰嗦,还容易漏字段类型(比如传了 int 却期望字符串)。

性能影响:用 slog.Stringslog.Int 等构造器,比直接传原始值略慢一点,但换来的是类型安全和结构化能力,值得。

实操建议:

  • 别硬改所有 Printf,优先在新模块、新服务里用 slog;老模块先加 slog.With("legacy", "true") 打标记,方便后期归因
  • slog.String("msg", fmt.Sprintf(...)) 临时过渡可以,但别长期留着——结构化日志的价值在于字段可检索,不是换了个壳继续拼字符串
  • 注意 error 类型字段会被 slog 自动展开(包括 stack trace,如果实现了 UnwrapStackTrace),不需要手动 fmt.Sprintf("%+v", err)

结构化日志真正难的不是语法,是决定哪些信息必须结构化、哪些可以丢进 message 字段——这取决于你的查询习惯和告警策略。字段一多,没人记得清 req_idrequest_id 哪个才是标准名。

text=ZqhQzanResources