Go - 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(couldnt start %s, user) }运行输出go run main.go {level:info,time:2026-03-10T20:41:0108:00,message:hello world} {level:warn,key1:value1,fnumber:12.34,time:2026-03-10T20:41:0108:00,message:this is a message} {level:error,error:this is an error,service:user,time:2026-03-10T20:41:0108:00,message:couldnt 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:3108:00 INF hello world 2026-03-10T21:00:3108:00 WRN this is a message fnumber12.34 key1value1日志级别Zerolog 支持以下日志级别按严重程度从高到低排列级别常量值说明paniczerolog.PanicLevel5记录日志后调用panic()fatalzerolog.FatalLevel4记录日志后调用os.Exit(1)errorzerolog.ErrorLevel3错误信息不影响程序继续运行warnzerolog.WarnLevel2警告信息潜在问题提示infozerolog.InfoLevel1一般信息默认级别debugzerolog.DebugLevel0调试信息开发环境使用tracezerolog.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:3908: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}})使用场景调试循环中的日志避免日志爆炸高并发接口的请求日志限流降级时的日志记录ContextZerolog 原生支持 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:2308:00,message:this is someFunc}HookHook 的作用是在日志写入前进行拦截处理可以实现一些通用逻辑给所有日志添加通用字段如服务名、环境、主机名根据日志级别做不同处理如错误日志发送到监控系统过滤敏感信息实现日志路由不同级别输出到不同目标实现 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:1708:00,severity:warn,message:this is a WARN level message} {level:info,time:2026-03-10T23:20:1708:00,message:send to sentry: this is a ERROR level message} {level:error,time:2026-03-10T23:20:1708:00,severity:error,message:this is a ERROR level message} {level:info,time:2026-03-10T23:20:1708:00,message:send to sentry: some value is error} {level:error,error:Value error,time:2026-03-10T23:20:1708: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:3308:00 INF Hello, World! 2026-03-10T21:23:3308:00 INF this is a metric metrics{cpupercent:51.23,memoryusage:11} $ tail logs/app.log {level:info,time:2026-03-10T21:23:3308:00,message:Hello, World!} {level:info,metrics:{cpupercent:51.23,memoryusage:11},time:2026-03-10T21:23:3308: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; charsetutf-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:3808: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:4008: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; charsetutf-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:4408: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/ginv1.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/ginv1.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/ginv1.12.0/context.go:192 0x5f\ngithub.com/gin-gonic/gin.(*Engine).handleHTTPRequest(0x33b8c2506380, 0x33b8c231a500)\n\tgithub.com/gin-gonic/ginv1.12.0/gin.go:722 0x45e\ngithub.com/gin-gonic/gin.(*Engine).ServeHTTP(0x33b8c2506380, {0xc2ba38, 0x33b8c252c000}, 0x33b8c2502500)\n\tgithub.com/gin-gonic/ginv1.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:4408: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:4408:00,caller:zerolog-exp/main.go:52,traceId:384ddafe-2434-433f-8fa4-883fda1580f3}