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，非常适合在请求链路中传递日志字段。

工作原理：

1. Logger.WithContext(ctx) 将 Logger 绑定到 context 中
2. zerolog.Ctx(ctx) 从 context 中取出 Logger
3. 取出的 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"}