Go Zerolog 怎样用 Hook 统一添加日志等级字段

我第一次把 zerolog 接进统一日志检索时，发现各个业务调用点的等级字段并不完全一致：有的只保留库默认的 level，有的又手写了 severity。继续在每个 Info、Warn、Error 后面补字段，很快就会出现漏写和命名漂移。

官方地址：https://github.com/rs/zerolog

先把“字段不一致”的症状拆开

Zerolog 的结构化事件自带等级信息，官方示例中的 Info、Warn 和 Error 会写出对应的 level 字段。真正容易失控的是业务团队为了适配不同日志平台，又在调用点各自补充别名字段。

我会先把问题限定在两个边界：日志等级由事件方法决定，字段映射由 Hook 集中负责。这样调用点只表达“这是一条什么等级的日志”，不会同时承担平台字段转换。

用 Hook.Run 统一补充 severity

Hook 的关键是实现 Run 方法。它拿到事件对象、等级和消息后，可以在事件写出前补充字段。下面的写法只把非空等级映射成 severity，保留 Zerolog 自己的 level 字段。

package main

import (
    "os"

    "github.com/rs/zerolog"
)

type SeverityHook struct{}

func (SeverityHook) Run(event *zerolog.Event, level zerolog.Level, _ string) {
    if level == zerolog.NoLevel {
        // Log() 没有明确等级时不猜测，避免把未知事件误标成 info。
        return
    }

    // 统一字段只在 Hook 中维护，业务调用点不再重复拼写。
    event.Str("severity", level.String())
}

func main() {
    logger := zerolog.New(os.Stdout).Hook(SeverityHook{})

    // 事件仍由调用方法决定等级，Hook 负责补充平台需要的别名字段。
    logger.Info().Msg("服务启动")
    logger.Error().Msg("读取配置失败")
}

这里的 severity 是新增字段，不是替换默认的 level。如果下游只接受一个固定字段，也可以在输出层或字段命名配置中统一策略，但不要在 Hook 和业务调用点同时写同名字段。

全局 logger、局部 logger 和字段边界

我在接入时遇到的第二个坑，是 Hook 只安装在一个 logger 实例上，却误以为所有日志都会继承。使用全局 log.Logger 时，应该明确替换全局实例；使用局部 logger 时，则要把 Hook 安装在真正被业务传递的那个实例上。

// 全局入口：替换 log 包实际使用的 Logger 实例。
log.Logger = log.Logger.Hook(SeverityHook{})

// 局部入口：把 Hook 放到服务自己的 logger，再向下传递它。
serviceLogger := zerolog.New(os.Stdout).
    Hook(SeverityHook{}).
    With().
    Str("component", "worker").
    Logger()

// 子 logger 继承父 logger 已配置的上下文，调用点只补充本地字段。
serviceLogger.Info().Str("job", "sync").Msg("开始处理")

安装范围要和依赖注入范围一致：全局安装适合单一日志出口，局部安装更适合多租户或多输出场景。无论哪种方式，都要约定 severity 的唯一写入者；如果某个业务确实要覆盖它，应把覆盖作为明确的输出策略，而不是默默重复添加。

把 NoLevel 和重复字段放进复查清单

Hook 并不意味着所有事件都天然有可用等级。官方 API 允许使用 Log() 写出不带具体等级的事件，因此 Hook 需要显式处理 NoLevel。在日志平台侧，还要确认字段名、大小写和枚举值是否符合既有查询规则。

对我来说，Hook 最有价值的地方不是少写几行 Str，而是把“日志等级如何映射为平台字段”从业务代码里抽出来。应用规模很小时，直接使用 Zerolog 默认的 level 已经够用；只有存在跨系统字段约定时，才值得增加这层统一逻辑。

常见问题

Hook 会替代 Zerolog 默认的 level 字段吗？

不会。示例中的 Hook 只是增加 severity；默认 level 仍由 Zerolog 输出。是否保留两个字段，应由下游平台的字段契约决定。

所有 Hook 都应该写 severity 吗？

不一定。Hook 适合集中处理跨模块都遵守的字段规则；如果只有一个模块需要特殊字段，把逻辑放在局部 logger 或业务边界通常更清晰。

为什么不把 NoLevel 直接当成 info？

因为 Log() 明确表达了“不指定等级”。强行映射成 info 会让查询结果看起来完整，却丢失了原始语义。