如何入门使用Go语言中的Zerolog日志库？
摘要：简介 Zerolog 是一个可以结构化输出 JSON 格式的 Go 日志库，其特点就是高性能，名字中的 zero 代表零分配设计，速度非常快。 什么是零分配设计？ 在 Go 语言中，内存分配会带来一定的性能开销，频繁的内存分配和垃圾回收（G
简介
Zerolog 是一个可以结构化输出 JSON 格式的 Go 日志库，其特点就是高性能，名字中的 zero 代表零分配设计，速度非常快。
什么是零分配设计？
在 Go 语言中，内存分配会带来一定的性能开销，频繁的内存分配和垃圾回收（GC）会影响程序性能。零分配设计的目标是在热点代码路径上尽量避免堆内存分配，从而减少 GC 压力，提升整体性能。
Zerolog 通过精心设计的 API 实现了这一目标：
链式调用返回指针而非值：避免了每次调用都创建新的对象
使用 sync.Pool 复用对象：日志事件对象会被放回池中重复利用
避免接口类型：直接使用具体类型，消除接口调用的开销
预分配缓冲区：减少写入时的内存分配
这种设计使得 Zerolog 在高并发场景下表现出色，尤其适合对性能敏感的服务端应用。
有人做了一个 Go 日志库 benchmark: https://betterstack-community.github.io/go-logging-benchmarks/，可以看出 zerolog 相较于其它日志库，性能都是第一档的，不管是执行速度还是内存占用，表现得都非常好。
特点
高性能：零分配设计，极高的写入速度，对 GC 几乎无压力。
结构化日志：默认输出 JSON 格式，便于日志系统（如 ELK、Loki）解析和检索。
支持 context：可以在请求链路中传递和追加日志字段，实现请求级别的日志追踪。
日志采样：对高频日志进行采样，防止日志风暴撑爆磁盘。
Hook 机制：可在日志写入前进行拦截处理，例如发送错误日志到 Sentry。
彩色输出：开发环境下可以启用彩色输出，提升可读性。
安装
go get github.com/rs/zerolog/log
基本使用
Zerolog 开箱即用，无需复杂配置即可快速上手。默认输出到 stderr，日志格式为 JSON，每条日志自动包含 level 和 time 字段。
Zerolog 采用链式调用风格，API 设计简洁直观：
log.Info()、log.Warn()、log.Error() 等方法创建对应级别的日志事件
Str()、Int()、Float64() 等方法添加自定义字段
Msg() 或 Msgf() 方法最终输出日志
package main
import (
"errors"
"github.com/rs/zerolog/log"
)
func main() {
log.Info().Msg("hello world")
log.Warn().Str("key1", "value1").Float64("fnumber", 12.34).Msg("this is a message")
err := errors.New("this is an error")
log.Error().Err(err).Str("service", "user").Msgf("couldn't start %s", "user")
}
运行输出：
go run main.go
{"level":"info","time":"2026-03-10T20:41:01+08:00","message":"hello world"}
{"level":"warn","key1":"value1","fnumber":12.34,"time":"2026-03-10T20:41:01+08:00","message":"this is a message"}
{"level":"error","error":"this is an error","service":"user","time":"2026-03-10T20:41:01+08:00","message":"couldn't start user"}
基本配置
可以进行一些基本配置：
package main
import (
"os"
"time"
"github.com/rs/zerolog"
"github.com/rs/zerolog/log"
)
func main() {
// 全局设置：设置 time 字段值为 unix 时间戳
zerolog.TimeFieldFormat = zerolog.TimeFormatUnix
// 全局设置：设置日志级别
zerolog.SetGlobalLevel(zerolog.DebugLevel)
// 输出到 stdout。开发环境可以输出到 console 中，生产环境还是用默认的 JSON 比较好
log.Logger = log.Output(zerolog.ConsoleWriter{Out: os.Stdout, NoColor: true, TimeFormat: time.RFC3339})
// 基本日志
log.Info().Msg("hello world")
// 链式调用：指定类型有助于性能
log.Warn().Str("key1", "value1").Float64("fnumber", 12.34).Msg("this is a message")
}
执行输出：
$ go run main.go
2026-03-10T21:00:31+08:00 INF hello world
2026-03-10T21:00:31+08:00 WRN this is a message fnumber=12.34 key1=value1
日志级别
Zerolog 支持以下日志级别，按严重程度从高到低排列：
级别
常量
值
说明
panic
zerolog.PanicLevel
5
记录日志后调用 panic()
fatal
zerolog.FatalLevel
4
记录日志后调用 os.Exit(1)
error
zerolog.ErrorLevel
3
错误信息，不影响程序继续运行
warn
zerolog.WarnLevel
2
警告信息，潜在问题提示
info
zerolog.InfoLevel
1
一般信息，默认级别
debug
zerolog.DebugLevel
0
调试信息，开发环境使用
trace
zerolog.TraceLevel
-1
最详细的追踪信息
使用建议：
生产环境建议设置为 InfoLevel 或 WarnLevel
开发环境可以设置为 DebugLevel 便于调试
panic 和 fatal 会中断程序，谨慎使用
添加调用者信息
package main
import (
"os"
"time"
"github.com/rs/zerolog"
)
func main() {
zerolog.TimeFieldFormat = time.RFC3339 // 全局设置时间格式为 RFC3339
zerolog.TimestampFieldName = "timestamp" // 全局设置时间字段名为 timestamp
zerolog.MessageFieldName = "msg" // 全局设置消息字段名为 msg
zerolog.SetGlobalLevel(zerolog.InfoLevel) // 全局设置日志级别为 InfoLevel
// 创建自定义日志记录器，添加时间戳、调用者信息
// Str("service", "backend") 可以在所有日志中添加服务名称
logger := zerolog.New(os.Stdout).With().Str("service", "backend").Timestamp().Caller().Logger()
logger.Debug().Msg("this is a debug message. it will not be logged")
logger.Info().Dict("metrics", zerolog.Dict().Str("remote_addr", "1.2.3.4").Int("status", 200)).Msg("this is a metric")
}
执行输出：
$ go run main.go | tail -n 1 | python3 -m json.tool
{
"level": "info",
"service": "backend",
"metrics": {
"remote_addr": "1.2.3.4",
"status": 200
},
"timestamp": "2026-03-10T22:33:39+08:00",
"caller": "/home/rainux/Documents/workspace/go-dev/zerolog-exp/main.go:21",
"msg": "this is a metric"
}
采样 - Sampling
采样功能用于控制日志输出频率，防止瞬间日志风暴快速塞满硬盘。这在调试某些高频循环或处理突发流量时特别有用。
Zerolog 提供了多种采样器：
// BasicSampler: 每 N 条日志只记录 1 条
log.Sample(&zerolog.BasicSampler{N: 100}).Info().Msg("High frequency log")
// BurstSampler: 每秒最多记录 N 条，超过后按给定比例采样
// 下面示例：每秒最多 100 条，超出后只记录 10%
log.Sample(&zerolog.BurstSampler{Burst: 100, Period: time.Second, NextSampler: &zerolog.BasicSampler{N: 10}})
使用场景：
调试循环中的日志，避免日志爆炸
高并发接口的请求日志
限流降级时的日志记录
Context
Zerolog 原生支持 Go 的 context.Context，非常适合在请求链路中传递日志字段。
工作原理：
Logger.WithContext(ctx) 将 Logger 绑定到 context 中
zerolog.Ctx(ctx) 从 context 中取出 Logger
取出的 Logger 会携带之前设置的所有字段
这种方式特别适合 Web 服务，可以在中间件中设置 request_id、user_id 等字段，然后在后续处理函数中直接使用。
package main
import (
"context"
"github.com/rs/zerolog"
"github.com/rs/zerolog/log"
)
func someFunc(ctx context.Context) {
logger := zerolog.Ctx(ctx)
logger.Info().Msg("this is someFunc")
}
func main() {
// 创建带 context 的 logger
ctxLogger := log.With().Str("request_id", "1234qwer").Logger().WithContext(context.Background())
someFunc(ctxLogger)
}
运行输出：
$ go run main.go
{"level":"info","request_id":"1234qwer","time":"2026-03-10T22:49:23+08:00","message":"this is someFunc"}
Hook
Hook 的作用是在日志写入前进行拦截处理，可以实现一些通用逻辑：
给所有日志添加通用字段（如服务名、环境、主机名）
根据日志级别做不同处理（如错误日志发送到监控系统）
过滤敏感信息
实现日志路由（不同级别输出到不同目标）
实现 Hook 只需定义一个结构体并实现 Run(e *zerolog.Event, level zerolog.Level, msg string) 方法。
package main
import (
"context"
"errors"
"github.com/rs/zerolog"
"github.com/rs/zerolog/log"
)
func someFunc(ctx context.Context) {
logger := zerolog.Ctx(ctx)
logger.Info().Msg("this is someFunc")
}
type SentryHook struct{}
func (h SentryHook) Run(e *zerolog.Event, level zerolog.Level, msg string) {
if level != zerolog.NoLevel {
e.Str("severity", level.String())
}
if level == zerolog.ErrorLevel {
// 错误日志发送到 sentry
log.Info().Msgf("send to sentry: %s", msg)
}
}
func main() {
hooked := log.Hook(SentryHook{})
hooked.Warn().Msg("this is a WARN level message")
hooked.Error().Msg("this is a ERROR level message")
err := errors.New("Value error")
hooked.Error().Err(err).Msg("some value is error")
}
运行输出，可以看到 hook 中的逻辑会先执行：
$ go run main.go
{"level":"warn","time":"2026-03-10T23:20:17+08:00","severity":"warn","message":"this is a WARN level message"}
{"level":"info","time":"2026-03-10T23:20:17+08:00","message":"send to sentry: this is a ERROR level message"}
{"level":"error","time":"2026-03-10T23:20:17+08:00","severity":"error","message":"this is a ERROR level message"}
{"level":"info","time":"2026-03-10T23:20:17+08:00","message":"send to sentry: some value is error"}
{"level":"error","error":"Value error","time":"2026-03-10T23:20:17+08:00","severity":"error","message":"some value is error"}
同时输出控制台和日志文件 + 自动轮转
在传统服务器上部署时，同时输出到控制台和日志文件是一个常见需求，并且还需要自动轮转以控制日志文件体积，防止日志撑爆硬盘资源。
如果服务部署在 Kubernetes 或 Docker 环境，有完善的日志监控系统可以采集控制台日志，可以直接去掉输出日志文件的功能。
package main
import (
"os"
"time"
"github.com/rs/zerolog"
"gopkg.in/natefinch/lumberjack.v2"
)
func main() {
consoleWriter := zerolog.ConsoleWriter{
Out: os.Stdout,
NoColor: false, // 输出颜色
TimeFormat: time.RFC3339, // 设置时间格式
PartsOrder: []string{"time", "level", "message"}, // 设置字段排列顺序
}
// 日志文件配置
lumberjackLogger := &lumberjack.Logger{
Filename: "logs/app.log", // 日志文件路径，lumberjack 会自动创建 logs 目录
MaxSize: 100, // 单个文件最大大小 (MB)
MaxBackups: 5, // 保留的旧文件最大数量
MaxAge: 30, // 文件最大保留时间 (天)
Compress: true, // 是否压缩旧日志 (gzip)
LocalTime: true, // 使用本地时间命名备份文件
}
multiwriter := zerolog.MultiLevelWriter(consoleWriter, lumberjackLogger)
logger := zerolog.New(multiwriter).With().Timestamp().Logger()
logger.Info().Msg("Hello, World!")
logger.Info().Dict("metrics", zerolog.Dict().Float64("cpupercent", 51.23).Int("memoryusage", 11)).Msg("this is a metric")
}
执行输出：
$ go run main.go
2026-03-10T21:23:33+08:00 INF Hello, World!
2026-03-10T21:23:33+08:00 INF this is a metric metrics={"cpupercent":51.23,"memoryusage":11}
$ tail logs/app.log
{"level":"info","time":"2026-03-10T21:23:33+08:00","message":"Hello, World!"}
{"level":"info","metrics":{"cpupercent":51.23,"memoryusage":11},"time":"2026-03-10T21:23:33+08:00","message":"this is a metric"}
在 Gin 中集成 zerolog
替代 Gin 默认的 logger 和 recovery 中间件：
package main
import (
"context"
"net"
"net/http"
"net/http/httputil"
"os"
"runtime/debug"
"strings"
"time"
"github.com/gin-gonic/gin"
"github.com/google/uuid"
"github.com/rs/zerolog"
"github.com/rs/zerolog/log"
)
const (
TRACING_KEY = "traceId"
)
type TracingHook struct{}
func (h TracingHook) Run(e *zerolog.Event, level zerolog.Level, msg string) {
ctx := e.GetCtx()
if ctx != nil {
if traceId, ok := ctx.Value(TRACING_KEY).(string); ok && traceId != "" {
e.Str(TRACING_KEY, traceId)
}
}
}
func ZeroLogMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
start := time.Now()
traceID := c.GetHeader("X-Trace-ID")
if traceID == "" {
traceID = uuid.New().String()
}
ctx := context.WithValue(c.Request.Context(), TRACING_KEY, traceID)
c.Request = c.Request.WithContext(ctx)
c.Header("X-Trace-ID", traceID)
c.Next()
log.Info().Ctx(ctx).
Str("method", c.Request.Method).
Str("path", c.Request.URL.Path).
Str("remote_addr", c.Request.RemoteAddr).
Int("status", c.Writer.Status()).
Int("response_size", c.Writer.Size()).Dur("latency", time.Since(start)).Msg("")
}
}
func ZeroLogRecovery() gin.HandlerFunc {
return func(c *gin.Context) {
defer func() {
if err := recover(); err != nil {
// 检查是否是连接中断（broken pipe）
var brokenPipe bool
if ne, ok := err.(*net.OpError); ok {
if se, ok := ne.Err.(*os.SyscallError); ok {
if strings.Contains(strings.ToLower(se.Error()), "broken pipe") ||
strings.Contains(strings.ToLower(se.Error()), "connection reset by peer") {
brokenPipe = true
}
}
}
// 获取堆栈信息
stack := string(debug.Stack())
// 获取原始请求内容
httpRequest, _ := httputil.DumpRequest(c.Request, false)
ctx := c.Request.Context()
if brokenPipe {
log.Error().Ctx(ctx).Any("error", err).Str("request", string(httpRequest)).Msg("network connection broken")
c.Abort()
return
}
log.Error().Ctx(ctx).Any("error", err).Str("stack", stack).Str("request", string(httpRequest)).Msg("recovery from panic")
traceID, _ := ctx.Value(TRACING_KEY).(string)
c.AbortWithStatusJSON(http.StatusInternalServerError, gin.H{
"code": http.StatusInternalServerError,
"msg": "Internal Server Error",
"data": nil,
"timestamp": time.Now().Format(time.RFC3339),
"trace_id": traceID,
})
}
}()
c.Next()
}
}
func main() {
zerolog.TimeFieldFormat = time.RFC3339
logger := zerolog.New(os.Stdout).With().Timestamp().Caller().Logger()
logger = logger.Hook(TracingHook{})
log.Logger = logger
r := gin.New()
r.Use(ZeroLogMiddleware())
r.Use(ZeroLogRecovery())
r.GET("/ping", func(c *gin.Context) {
log.Info().Ctx(c.Request.Context()).Msg("get a ping request")
time.Sleep(2 * time.Second)
c.String(200, "pong")
})
r.GET("/panic", func(c *gin.Context) {
log.Info().Ctx(c.Request.Context()).Msg("get a panic request")
panic("something went wrong")
})
r.Run("127.0.0.1:10000")
}
请求测试，可以看到响应头中已经包含了 TraceID：
$ curl http://127.0.0.1:10000/ping -v
* Trying 127.0.0.1:10000...
* Connected to 127.0.0.1 (127.0.0.1) port 10000
* using HTTP/1.x
> GET /ping HTTP/1.1
> Host: 127.0.0.1:10000
> User-Agent: curl/8.14.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 200 OK
< Content-Type: text/plain; charset=utf-8
< X-Trace-Id: 22c92423-2e95-4ded-934f-f0fd51f36cc7
< Date: Tue, 10 Mar 2026 16:13:40 GMT
< Content-Length: 4
<
* Connection #0 to host 127.0.0.1 left intact
pong
在服务端日志中也能看到对应的日志记录：
{"level":"info","time":"2026-03-11T00:13:38+08:00","caller":"/home/rainux/Documents/workspace/go-dev/zerolog-exp/main.go:63","traceId":"22c92423-2e95-4ded-934f-f0fd51f36cc7","message":"get a ping request"}
{"level":"info","method":"GET","path":"/ping","remote_addr":"127.0.0.1:56540","status":200,"response_size":4,"latency":2001.158295,"time":"2026-03-11T00:13:40+08:00"}
再试试异常恢复功能：
$ curl http://127.0.0.1:10000/panic -v
* Trying 127.0.0.1:10000...
* Connected to 127.0.0.1 (127.0.0.1) port 10000
* using HTTP/1.x
> GET /panic HTTP/1.1
> Host: 127.0.0.1:10000
> User-Agent: curl/8.14.1
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 500 Internal Server Error
< Content-Type: application/json; charset=utf-8
< X-Trace-Id: 384ddafe-2434-433f-8fa4-883fda1580f3
< Date: Tue, 10 Mar 2026 16:34:44 GMT
< Content-Length: 144
<
* Connection #0 to host 127.0.0.1 left intact
{"code":500,"data":null,"msg":"Internal Server Error","timestamp":"2026-03-11T00:34:44+08:00","trace_id":"384ddafe-2434-433f-8fa4-883fda1580f3"}
在服务端也能观察到相应的报错堆栈信息：
{"level":"error","error":"something went wrong","stack":"goroutine 8 [running]:\nruntime/debug.Stack()\n\truntime/debug/stack.go:26 +0x5e\nmain.main.ZeroLogRecovery.func4.1()\n\tzerolog-exp/main.go:71 +0x105\npanic({0xb26900?, 0xc24a00?})\n\truntime/panic.go:860 +0x13a\nmain.main.func2(0x33b8c231a500)\n\tzerolog-exp/main.go:121 +0x7a\ngithub.com/gin-gonic/gin.(*Context).Next(0x33b8c231a500)\n\tgithub.com/gin-gonic/gin@v1.12.0/context.go:192 +0x5f\nmain.main.ZeroLogRecovery.func4(0x33b8c250ac00?)\n\tzerolog-exp/main.go:97 +0x3f\ngithub.com/gin-gonic/gin.(*Context).Next(0x33b8c231a500)\n\tgithub.com/gin-gonic/gin@v1.12.0/context.go:192 +0x5f\nmain.main.ZeroLogMiddleware.func3(0x33b8c231a500)\n\tzerolog-exp/main.go:46 +0x154\ngithub.com/gin-gonic/gin.(*Context).Next(0x33b8c231a500)\n\tgithub.com/gin-gonic/gin@v1.12.0/context.go:192 +0x5f\ngithub.com/gin-gonic/gin.(*Engine).handleHTTPRequest(0x33b8c2506380, 0x33b8c231a500)\n\tgithub.com/gin-gonic/gin@v1.12.0/gin.go:722 +0x45e\ngithub.com/gin-gonic/gin.(*Engine).ServeHTTP(0x33b8c2506380, {0xc2ba38, 0x33b8c252c000}, 0x33b8c2502500)\n\tgithub.com/gin-gonic/gin@v1.12.0/gin.go:672 +0x1dc\nnet/http.serverHandler.ServeHTTP({0x33b8c23f5dc0?}, {0xc2ba38?, 0x33b8c252c000?}, 0x1?)\n\tnet/http/server.go:3311 +0x8e\nnet/http.(*conn).serve(0x33b8c24ae5a0, {0xc2c0f0, 0x33b8c250aa20})\n\tnet/http/server.go:2073 +0x650\ncreated by net/http.(*Server).Serve in goroutine 1\n\tnet/http/server.go:3464 +0x485\n","request":"GET /panic HTTP/1.1\r\nHost: 127.0.0.1:10000\r\nAccept: */*\r\nUser-Agent: curl/8.14.1\r\n\r\n","time":"2026-03-11T00:34:44+08:00","caller":"zerolog-exp/main.go:83","traceId":"384ddafe-2434-433f-8fa4-883fda1580f3","message":"recovery from panic"}
{"level":"info","method":"GET","path":"/panic","remote_addr":"127.0.0.1:42380","status":500,"response_size":144,"latency":0.184455,"time":"2026-03-11T00:34:44+08:00","caller":"zerolog-exp/main.go:52","traceId":"384ddafe-2434-433f-8fa4-883fda1580f3"}