Go Zerolog使用入门教程
简介
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"}到此这篇关于Go Zerolog使用入门的文章就介绍到这了,更多相关Go Zerolog使用内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！
相关文章
中间件是Gin框架中的一个重要概念,它可以用来处理HTTP请求和响应,或者在处理请求之前和之后执行一些操作,本文主要介绍了Go Gin中间件的具体使用,感兴趣的可以了解一下2023-11-11
本文介绍与文件路径相关包，该工具包位于path/filepath中，该包试图与目标操作系统定义的文件路径兼容。本文介绍一些常用函数，如获取文件绝对路径，获取文件名或目录名、遍历文件、分割文件路径、文件名模式匹配等函数，并给具体示例进行说明2023-02-02
本文主要介绍了Go手写数据库ZiyiDB的实现,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧2025-05-05
前段时间在一个项目里使用到了分布式锁进行共享资源的访问限制，后来了解到Golang里还能够使用singleflight对共享资源的访问做限制，于是利用空余时间了解，将知识沉淀下来,并做分享2022-05-05
今天小编就为大家分享一篇关于在Go中构建并发TCP服务器的文章，小编觉得内容挺不错的，现在分享给大家，具有很好的参考价值，需要的朋友一起跟随小编来看看吧2018-10-10
在Go语言中,函数和方法在声明方式上存在显著差异,理解这一点是正确解读文档的关键,这篇文章主要介绍了Go语言基础教程之函数和方法的相关资料,文中通过代码介绍的非常详细,需要的朋友可以参考下2025-10-10
这篇文章主要对Golang的sync.Pool对象池对象重用机制做了一个总结，文中有相关的代码示例和图解，具有一定的参考价值,需要的朋友可以参考下2023-07-07
这篇文章主要为大家介绍了go语言csrf库使用实现原理示例解析，有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪2022-10-10
Go gorilla securecookie库的安装使用详解
这篇文章主要介绍了Go gorilla securecookie库的安装使用详解,有需要的朋友可以借鉴参考下，希望能够有所帮助，祝大家多多进步，早日升职加薪2022-08-08
这篇文章主要给大家介绍了关于vscode上搭建go开发环境的详细完整过程,Go语言或将成为新的主力开发语言,Go是google开发的一种静态强类型、编译型、并发型,并具有垃圾回收功能的编程语言,所以我们有必要学习并掌握它,需要的朋友可以参考下2023-10-10
最新评论