博客 / 詳情

返回

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"}
後端
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.