Zerolog 实战指南：Go 语言最快的结构化日志库

Zerolog 是 Go 生态中以性能著称的结构化日志库，核心设计目标是零内存分配——高频写日志时几乎不给 GC 增加压力。它默认输出 JSON，API 采用流畅的链式调用。本文覆盖 Zerolog 的核心用法、上下文绑定、采样降噪与生产配置，并给出观测云平台的落地方案。

核心要点速览

• Zerolog 是 Go 最快的结构化日志库之一：零分配设计，在各类基准测试中常年领先，适合高吞吐服务。
• 默认输出 JSON：每条日志天然是结构化文档，开发期可用 ConsoleWriter 转成彩色可读格式。
• 链式事件 API：log.Info().Str("user", u).Int("code", c).Msg("...")，字段在 Msg 前的链上逐个附加。
• 生产落地：JSON 输出 stdout，观测云 DataKit 采集解析，监控器告警，多索引控成本。

快速上手：链式 API 与日志级别

package main

import "github.com/rs/zerolog/log"

func main() {
    log.Debug().Msg("调试细节")  // 默认级别 trace，全都输出
    log.Info().Str("user", "zhangsan").Msg("用户登录")
    log.Warn().Msg("配置项缺失，使用默认值")
    log.Error().Err(err).Str("order_id", "A-1024").Msg("扣款失败")
}

输出（默认 JSON）：

{"level":"info","user":"zhangsan","time":"2026-08-25T14:35:10+08:00","message":"用户登录"}
{"level":"error","error":"insufficient balance","order_id":"A-1024","time":"...","message":"扣款失败"}

Zerolog 提供七个级别：Trace、Debug、Info、Warn、Error、Fatal、Panic。Fatal 记完即调 os.Exit(1)，Panic 记完即 panic——生产代码慎用。

全局级别用 zerolog.SetGlobalLevel(zerolog.InfoLevel) 设置；字段方法覆盖所有常见类型：Str()、Int()、Bool()、Dur()、Time()、Err() 等。

如何创建定制 Logger？

包级 log 是全局默认 logger，生产建议显式创建实例：

logger := zerolog.New(os.Stdout).
    With().
    Timestamp().
    Str("service", "order-api").
    Logger()

With() 返回 Context 对象，链上绑定的字段（service、版本、实例 ID）会出现在该 logger 的所有日志里；再加 Caller() 可附带源码位置。

开发环境：ConsoleWriter 友好输出

logger := zerolog.New(zerolog.ConsoleWriter{Out: os.Stderr, TimeFormat: time.RFC3339}).
    Level(zerolog.DebugLevel).With().Timestamp().Caller().Logger()

彩色对齐的纯文本输出，开发体验拉满；生产切回 JSON 输出即可。

错误与堆栈怎么记？

Err(err) 会把错误写入 error 字段。需要堆栈时，配合 pkg/errors 并启用：

zerolog.ErrorStackMarshaler = func(err error) interface{} {
    return pkgerrors.MarshalStack(err)
}

之后 log.Error().Stack().Err(err).Msg("...") 会输出结构化堆栈字段。排障价值巨大，建议在错误日志中默认开启。

高级能力：Hook、采样与 context 集成

Hook：给特定级别统一附加字段

logger = logger.Hook(zerolog.HookFunc(func(e *zerolog.Event, level zerolog.Level, msg string) {
    if level >= zerolog.ErrorLevel {
        e.Str("alert_hint", "check-oncall")
    }
}))

采样：高频日志降噪

sampled := logger.Sample(&zerolog.BasicSampler{N: 100})  // 每 100 条只记 1 条
sampled.Info().Msg("高频心跳日志")

对每秒数千条的 DEBUG/INFO 流水，采样能把日志量压到原来的零头，配合观测云的低频索引进一步控制成本。

从 context.Context 取 logger

Zerolog 提供 zerolog.Ctx(ctx) 与 (*Logger).WithContext(ctx) 帮助函数，实现"logger 随请求 context 流转"：

ctx := reqLogger.WithContext(r.Context())
// 下游：
log := zerolog.Ctx(ctx)
log.Info().Msg("处理中")

请求级字段（request_id 等）绑在 reqLogger 上一次，下游自动携带。

观测云落地：Zerolog 日志采集与分析

1. 应用侧：生产固定 JSON 输出 stdout；level 字段 Zerolog 默认小写（debug/info/warn/error），与观测云 status 语义天然接近。
2. DataKit 采集：容器 stdout 自动采集，JSON 解析为字段；logging.conf 中 source 设为 go-app、service 区分服务。
3. Pipeline 标准化：把 level 映射为标准 status 字段（error/fatal/panic → error，warn → warning），time 解析为事件时间。
4. 检索告警：日志查看器按 status/service 过滤与聚类；监控器对 error 及以上级别设阈值告警，钉钉/企业微信/飞书触达。
5. 链路关联：OTel 接入后把 trace_id 注入 Zerolog 字段（Hook 或 ctx 方案），与观测云 APM 双向跳转。
6. 成本控制：采样 + 低频索引 + 数据转发归档三件套，高吞吐服务日志成本可降一个数量级。

常见问题（FAQ）

Zerolog 和标准库 slog 怎么选？

新项目默认建议 slog（标准库、零依赖、生态在向它收敛）；确认日志吞吐是性能瓶颈、或需要 Zerolog 独有的采样/二进制 CBOR 输出时选 Zerolog。也可以让 Zerolog 作为 slog 的 Handler 后端，兼得两者。

Zerolog 支持文本格式输出吗？

只支持 JSON（及 CBOR 二进制）。文本输出靠 ConsoleWriter 在写入前转换，本质是开发期工具；生产请保持 JSON，交给日志平台解析。

Fatal 和 Panic 级别会导致程序退出吗？

会。log.Fatal() 记录后调用 os.Exit(1)（defer 不会执行），log.Panic() 记录后 panic。只在确实不可恢复的启动期错误使用 Fatal；请求处理路径上的错误用 Error。

Zerolog 如何做日志轮转？

库本身不管轮转——它只写 io.Writer。主机部署把日志文件交给系统 logrotate（copytruncate）；需要应用内轮转时用 lumberjack 作为 writer；容器部署直接 stdout 最省心。

系列阅读

• 上一篇：Go 上下文日志实战
• 下一篇：Zap 实战指南
• 相关阅读：Go 日志库九款对比 ｜ 日志采样详解

---