博客 / 詳情

返回

Go - slog使用入門

簡介

slog 是 Go 1.21 引入的官方結構化日誌庫（Structured Logging）。它結束了 Go 標準庫只有簡單 log 包的歷史，讓我們可以直接輸出 JSON 或 Key-Value 格式的日誌，非常適合對接 ELK、Grafana Loki 等日誌分析系統。

相較於第三方日誌庫如 zap、logrus，slog 的優勢在於：

  • 零依賴：作為標準庫的一部分，無需引入第三方依賴
  • 官方維護：長期穩定，API 變更有 Go 兼容性承諾保障
  • 接口簡潔：API 設計清晰，學習成本低
  • 可擴展：通過自定義 Handler 可以實現各種定製需求

基本使用

slog 用起來非常簡單。默認輸出到標準錯誤流（os.Stderr），格式為普通文本。

package main

import (
	"fmt"
	"log/slog"
)

func main() {
	slog.Debug("Hello world")
	slog.Info("Hello world")
	slog.Warn("Hello world")
	slog.Error("Hello world")

	slog.Info("this is a message", "name", "zhangsan")

	age := 8
	slog.Warn(fmt.Sprintf("這是 %d 歲?", age))
}

運行輸出：

$ go run main.go
2026/02/15 11:52:24 INFO Hello world
2026/02/15 11:52:24 WARN Hello world
2026/02/15 11:52:24 ERROR Hello world
2026/02/15 11:52:24 INFO this is a message name=zhangsan
2026/02/15 11:52:24 WARN 這是 8 歲?

注意：默認的 slog logger 日誌級別為 INFO，因此 Debug 級別的日誌不會輸出。

日誌級別

slog 定義了四個日誌級別，從低到高依次為：

級別 常量 説明
DEBUG slog.LevelDebug 調試信息，開發環境使用
INFO slog.LevelInfo 常規信息
WARN slog.LevelWarn 警告信息
ERROR slog.LevelError 錯誤信息

輸出 JSON 格式

slog 可以輸出 JSON 格式，便於與 ELK、Grafana Loki 等日誌系統集成。

以下示例演示瞭如何修改默認的時間戳格式和調用源輸出格式，並將其設置為默認 logger：

package main

import (
	"fmt"
	"log/slog"
	"os"
	"time"
)

func main() {
	jsonLogger := slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{
		AddSource: true,            // 添加調用源信息
		Level:     slog.LevelDebug, // 設置日誌級別
		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			// 自定義時間格式
			if a.Key == slog.TimeKey {
				if t, ok := a.Value.Any().(time.Time); ok {
					a.Value = slog.StringValue(t.Format(time.RFC3339))
				}
			}
			// 簡化調用源信息，只保留文件名和行號
			if a.Key == slog.SourceKey {
				source := a.Value.Any().(*slog.Source)
				shortFile := source.File
				for i := len(source.File) - 1; i > 0; i-- {
					if source.File[i] == '/' {
						shortFile = source.File[i+1:]
						break
					}
				}
				return slog.String("source", fmt.Sprintf("%s:%d", shortFile, source.Line))
			}
			return a
		},
	}))

	jsonLogger.Debug("Hello world")
	jsonLogger.Info("Hello world")
	jsonLogger.Warn("Hello world")
	jsonLogger.Error("Hello world")

	jsonLogger.Info("this is a message", "name", "zhangsan")

	age := 8
	jsonLogger.Warn(fmt.Sprintf("這是 %d 歲?", age))

	// 替換默認 logger
	slog.SetDefault(jsonLogger)
	slog.Debug("Hello world")
	slog.Info("Hello world")
	slog.Warn("Hello world")
	slog.Error("Hello world")

	slog.Info("this is a message", "name", "zhangsan")

	age = 9
	slog.Warn(fmt.Sprintf("這是 %d 歲?", age))
}

運行輸出：

$ go run main.go
{"time":"2026-02-15T12:07:32+08:00","level":"DEBUG","source":"main.go:38","msg":"Hello world"}
{"time":"2026-02-15T12:07:32+08:00","level":"INFO","source":"main.go:39","msg":"Hello world"}
{"time":"2026-02-15T12:07:32+08:00","level":"WARN","source":"main.go:40","msg":"Hello world"}
{"time":"2026-02-15T12:07:32+08:00","level":"ERROR","source":"main.go:41","msg":"Hello world"}
{"time":"2026-02-15T12:07:32+08:00","level":"INFO","source":"main.go:43","msg":"this is a message","name":"zhangsan"}
{"time":"2026-02-15T12:07:32+08:00","level":"WARN","source":"main.go:46","msg":"這是 8 歲?"}
{"time":"2026-02-15T12:07:32+08:00","level":"DEBUG","source":"main.go:50","msg":"Hello world"}
{"time":"2026-02-15T12:07:32+08:00","level":"INFO","source":"main.go:51","msg":"Hello world"}
{"time":"2026-02-15T12:07:32+08:00","level":"WARN","source":"main.go:52","msg":"Hello world"}
{"time":"2026-02-15T12:07:32+08:00","level":"ERROR","source":"main.go:53","msg":"Hello world"}
{"time":"2026-02-15T12:07:32+08:00","level":"INFO","source":"main.go:55","msg":"this is a message","name":"zhangsan"}
{"time":"2026-02-15T12:07:32+08:00","level":"WARN","source":"main.go:58","msg":"這是 9 歲?"}

HandlerOptions 詳解

HandlerOptions 提供了三個配置項：

字段 類型 説明
AddSource bool 是否添加調用源信息（文件名和行號）
Level slog.Leveler 最低日誌級別，低於此級別的日誌將被忽略
ReplaceAttr func([]string, slog.Attr) slog.Attr 用於修改或替換屬性的回調函數

With 注入通用屬性

創建 Logger 時，可以用 With 方法為 logger 添加通用屬性。這些屬性會自動附加到每條日誌記錄中，適合注入服務名、環境、版本等上下文信息。

package main

import (
	"fmt"
	"log/slog"
	"os"
	"time"
)

func main() {
	jsonLogger := slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{
		AddSource: true,
		Level:     slog.LevelDebug,
		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			if a.Key == slog.TimeKey {
				if t, ok := a.Value.Any().(time.Time); ok {
					a.Value = slog.StringValue(t.Format(time.RFC3339))
				}
			}
			if a.Key == slog.SourceKey {
				source := a.Value.Any().(*slog.Source)
				shortFile := source.File
				for i := len(source.File) - 1; i > 0; i-- {
					if source.File[i] == '/' {
						shortFile = source.File[i+1:]
						break
					}
				}
				return slog.String("source", fmt.Sprintf("%s:%d", shortFile, source.Line))
			}
			return a
		},
	})).With("logger", "json", "env", "production")

	jsonLogger.Debug("Hello world")
	jsonLogger.Info("Hello world")
	jsonLogger.Warn("Hello world")
	jsonLogger.Error("Hello world")

	jsonLogger.Info("this is a message", "name", "zhangsan")
}

運行輸出：

$ go run main.go
{"time":"2026-02-15T13:24:38+08:00","level":"DEBUG","source":"main.go:42","msg":"Hello world","logger":"json","env":"production"}
{"time":"2026-02-15T13:24:38+08:00","level":"INFO","source":"main.go:43","msg":"Hello world","logger":"json","env":"production"}
{"time":"2026-02-15T13:24:38+08:00","level":"WARN","source":"main.go:44","msg":"Hello world","logger":"json","env":"production"}
{"time":"2026-02-15T13:24:38+08:00","level":"ERROR","source":"main.go:45","msg":"Hello world","logger":"json","env":"production"}
{"time":"2026-02-15T13:24:38+08:00","level":"INFO","source":"main.go:47","msg":"this is a message","logger":"json","env":"production","name":"zhangsan"}

使用 Group 對屬性分組

當日志屬性較多時，可以使用 slog.Group 將相關屬性組織在一起，使輸出結構更清晰：

package main

import (
	"fmt"
	"log/slog"
	"os"
	"time"
)

func main() {
	jsonLogger := slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{
		AddSource: true,
		Level:     slog.LevelDebug,
		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			if a.Key == slog.TimeKey {
				if t, ok := a.Value.Any().(time.Time); ok {
					a.Value = slog.StringValue(t.Format(time.RFC3339))
				}
			}
			if a.Key == slog.SourceKey {
				source := a.Value.Any().(*slog.Source)
				shortFile := source.File
				for i := len(source.File) - 1; i > 0; i-- {
					if source.File[i] == '/' {
						shortFile = source.File[i+1:]
						break
					}
				}
				return slog.String("source", fmt.Sprintf("%s:%d", shortFile, source.Line))
			}
			return a
		},
	}))

	jsonLogger = jsonLogger.With("logger", "json")

	// 使用 Group 組織相關屬性
	jsonLogger.Info("系統狀態",
		slog.Group("metrics",
			slog.Int("cpu", 4),
			slog.Float64("memPercent", 2.33),
		),
		slog.Group("request",
			slog.String("method", "GET"),
			slog.String("path", "/api/users"),
		),
	)
}

運行輸出：

$ go run main.go
{"time":"2026-02-15T13:30:08+08:00","level":"INFO","source":"main.go:43","msg":"系統狀態","logger":"json","metrics":{"cpu":4,"memPercent":2.33},"request":{"method":"GET","path":"/api/users"}}

高性能場景使用 LogAttrs

如果需要在高性能循環中打印日誌，建議使用 LogAttrs 方法。它使用強類型屬性（slog.Attr），避免了反射帶來的性能開銷。

package main

import (
	"context"
	"log/slog"
	"os"
	"time"
)

func main() {
	jsonLogger := slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{
		AddSource: true,
		Level:     slog.LevelDebug,
		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			if a.Key == slog.TimeKey {
				if t, ok := a.Value.Any().(time.Time); ok {
					a.Value = slog.StringValue(t.Format(time.RFC3339))
				}
			}
			if a.Key == slog.SourceKey {
				source := a.Value.Any().(*slog.Source)
				shortFile := source.File
				for i := len(source.File) - 1; i > 0; i-- {
					if source.File[i] == '/' {
						shortFile = source.File[i+1:]
						break
					}
				}
				return slog.String("source", fmt.Sprintf("%s:%d", shortFile, source.Line))
			}
			return a
		},
	})).With("logger", "json")

	for i := range 5 {
		jsonLogger.LogAttrs(
			context.Background(),
			slog.LevelInfo,
			"執行遍歷",
			slog.Int("round", i),
			slog.String("task_name", "cleanup"),
			slog.Duration("duration", time.Second*time.Duration(i+1)),
		)
	}
}

運行輸出：

$ go run main.go
{"time":"2026-02-15T13:38:21+08:00","level":"INFO","source":"main.go:45","msg":"執行遍歷","logger":"json","round":0,"task_name":"cleanup","duration":1000000000}
{"time":"2026-02-15T13:38:21+08:00","level":"INFO","source":"main.go:45","msg":"執行遍歷","logger":"json","round":1,"task_name":"cleanup","duration":2000000000}
{"time":"2026-02-15T13:38:21+08:00","level":"INFO","source":"main.go:45","msg":"執行遍歷","logger":"json","round":2,"task_name":"cleanup","duration":3000000000}
{"time":"2026-02-15T13:38:21+08:00","level":"INFO","source":"main.go:45","msg":"執行遍歷","logger":"json","round":3,"task_name":"cleanup","duration":4000000000}
{"time":"2026-02-15T13:38:21+08:00","level":"INFO","source":"main.go:45","msg":"執行遍歷","logger":"json","round":4,"task_name":"cleanup","duration":5000000000}

性能對比

根據官方基準測試，LogAttrs 相比普通方法調用有約 30% 的性能提升：

方法 內存分配 性能
slog.Info(msg, "key", value) 有額外分配 基準
slog.LogAttrs(ctx, level, msg, attrs...) 零額外分配 快約 30%

提取 Context 中的鏈路信息

slog 提供了 InfoContext、WarnContext 等方法，可以從 context.Context 中提取數據。默認情況下，這些方法不會自動提取 context 中的值，需要通過自定義 Handler 來實現。

自定義 ContextHandler

以下示例實現了一個自定義 Handler，用於從 context 中提取 TraceID：

package main

import (
	"context"
	"log/slog"
	"os"
)

type contextKey string

const TraceIDKey contextKey = "trace_id"

// ContextHandler 包裝一個 slog.Handler，在處理日誌時自動從 context 中提取 TraceID
type ContextHandler struct {
	slog.Handler
}

func (h *ContextHandler) Handle(ctx context.Context, record slog.Record) error {
	if ctx != nil {
		if traceID, ok := ctx.Value(TraceIDKey).(string); ok && traceID != "" {
			record.AddAttrs(slog.String(string(TraceIDKey), traceID))
		}
	}
	return h.Handler.Handle(ctx, record)
}

func main() {
	baseHandler := slog.NewJSONHandler(os.Stdout, nil)
	handler := &ContextHandler{Handler: baseHandler}
	jsonLogger := slog.New(handler)
	slog.SetDefault(jsonLogger)

	ctx := context.WithValue(context.Background(), TraceIDKey, "abc123-def456")

	slog.InfoContext(ctx, "hello world")
	slog.WarnContext(ctx, "something happened", "user", "zhangsan")
}

運行輸出：

$ go run main.go | python3 -m json.tool
{
  "time": "2026-02-15T13:56:43.086323769+08:00",
  "level": "INFO",
  "msg": "hello world",
  "trace_id": "abc123-def456"
}
{
  "time": "2026-02-15T13:56:43.086323769+08:00",
  "level": "WARN",
  "msg": "something happened",
  "user": "zhangsan",
  "trace_id": "abc123-def456"
}

在 Gin 框架中使用 slog

在 Gin 中使用 slog 的 context 能力，通常的做法是編寫一箇中間件來注入 TraceID，並配合自定義 slog.Handler 來提取它。

package main

import (
	"context"
	"log/slog"
	"net"
	"net/http"
	"net/http/httputil"
	"os"
	"runtime/debug"
	"strings"
	"time"

	"github.com/gin-gonic/gin"
	"github.com/google/uuid"
)

type contextKey string

const TraceIDKey contextKey = "trace_id"

// ContextHandler 從 context 中提取 TraceID 並添加到日誌中
type ContextHandler struct {
	slog.Handler
}

func (h *ContextHandler) Handle(ctx context.Context, record slog.Record) error {
	if ctx != nil {
		if traceID, ok := ctx.Value(TraceIDKey).(string); ok && traceID != "" {
			record.AddAttrs(slog.String(string(TraceIDKey), traceID))
		}
	}
	return h.Handler.Handle(ctx, record)
}

// SlogMiddleware 是一個 Gin 中間件，用於注入 TraceID
func SlogMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		start := time.Now()

		// 優先從請求頭獲取 TraceID，沒有則生成新的
		traceID := c.GetHeader("X-Trace-ID")
		if traceID == "" {
			traceID = uuid.New().String()
		}

		// 將 TraceID 注入到標準的 context.Context 中
		// 注意：Gin 的 c.Set 只在 Gin 內部生效，slog 需要標準庫的 Context
		ctx := context.WithValue(c.Request.Context(), TraceIDKey, traceID)
		c.Request = c.Request.WithContext(ctx)

		// 將 TraceID 寫入響應頭，方便客户端追蹤
		c.Header("X-Trace-ID", traceID)

		c.Next()

		// 請求結束後的彙總日誌
		slog.InfoContext(c.Request.Context(), "Request completed",
			slog.String("method", c.Request.Method),
			slog.String("path", c.Request.URL.Path),
			slog.Int("status", c.Writer.Status()),
			slog.Int("body_size", c.Writer.Size()),
			slog.Duration("latency", time.Since(start)),
		)
	}
}

// SlogRecovery 是一個自定義的恢復中間件
// 它會捕獲 Panic，記錄堆棧信息，並使用 slog.ErrorContext 輸出
func SlogRecovery() 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)

				if brokenPipe {
					slog.ErrorContext(c.Request.Context(), "網絡連接中斷",
						slog.Any("error", err),
						slog.String("request", string(httpRequest)),
					)
					c.Error(err.(error))
					c.Abort()
					return
				}

				// 記錄 Panic 詳情
				slog.ErrorContext(c.Request.Context(), "Recovery from panic",
					slog.Any("error", err),
					slog.String("stack", stack),
					slog.String("request", string(httpRequest)),
				)

				ctx := c.Request.Context()
				traceID, _ := ctx.Value(TraceIDKey).(string)

				// 返回 500 狀態碼
				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() {
	// 初始化 slog
	baseHandler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: slog.LevelDebug,
	})
	handler := &ContextHandler{Handler: baseHandler}
	jsonLogger := slog.New(handler)
	slog.SetDefault(jsonLogger)

	// 使用 gin.New() 而不是 gin.Default()，避免內置日誌干擾
	r := gin.New()
	r.Use(SlogMiddleware())
	r.Use(SlogRecovery())

	r.GET("/ping", func(c *gin.Context) {
		slog.InfoContext(c.Request.Context(), "Processing /ping request",
			slog.String("user", "zhangsan"),
		)

		time.Sleep(time.Second * 2)
		c.JSON(200, gin.H{"msg": "pong"})
	})

	r.GET("/panic", func(c *gin.Context) {
		slog.InfoContext(c.Request.Context(), "About to panic")
		panic("something went wrong")
	})

	r.Run(":8080")
}

運行後測試：

$ curl http://localhost:8080/ping
{"msg":"pong"}

$ curl http://localhost:8080/panic
{"code":500,"msg":"Internal Server Error","data":null,"timestamp":"2026-02-15T14:30:00+08:00","trace_id":"xxx-xxx-xxx"}

日誌輸出文件

寫日誌文件一定要注意控制日誌文件大小，建議配合系統的logrotate。如果服務運行在kubernetes，建議只輸出控制枱日誌，由專門的日誌收集平台去獲取控制枱日誌。

基本實現

寫到app.log中

package main

import (
	"log/slog"
	"os"
)

func main() {
	logFile, err := os.OpenFile("app.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
	if err != nil {
		panic(err)
	}
	handler := slog.NewJSONHandler(logFile, nil)
	logger := slog.New(handler)
	slog.SetDefault(logger)

	slog.Info("hello world")

}

配合logrotate。在 /etc/logrotate.d/myapp 創建配置文件

/path/to/app.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    copytruncate    # 複製後截斷，不需要重啓 Go 程序
}

使用lumberjack輪轉日誌文件

如果不想用系統的 logrotate ，可以使用 lumberjack 包，它提供了更靈活的日誌輪轉策略。

import "gopkg.in/natefinch/lumberjack.v2"

func initLumberjack() {
    rollingFile := &lumberjack.Logger{
        Filename:   "./logs/app.log",
        MaxSize:    100, // 單位 MB
        MaxBackups: 3,   // 保留舊文件的最大個數
        MaxAge:     28,  // 保留舊文件的最大天數
        Compress:   true, // 是否壓縮
    }

    handler := slog.NewJSONHandler(rollingFile, nil)
    slog.SetDefault(slog.New(handler))
}

同時輸出控制枱和日誌文件

go1.26 版本後實現了slog.NewMultiHandler，1.26 前可使用io.multiwriter。

package main

import (
	"log/slog"
	"os"
)

func main() {
	logFile, err := os.OpenFile("app.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
	if err != nil {
		panic(err)
	}
	fileHandler := slog.NewJSONHandler(logFile, nil)
	consoleHandler := slog.NewTextHandler(os.Stdout, nil)
	multiHandler := slog.NewMultiHandler(fileHandler, consoleHandler) // slog.NewMultiHandler 需要go1.26.0+版本
	logger := slog.New(multiHandler)
	slog.SetDefault(logger)

	slog.Info("hello world")

}

自定義日誌級別

除了四個內置級別，slog 還支持自定義日誌級別 (一般來説默認的日誌級別已經夠用了)：

package main

import (
	"log/slog"
	"os"
)

func main() {
	// 定義自定義日誌級別
	const (
		LevelTrace   = slog.Level(-8) // 比 Debug 更低
		LevelNotice  = slog.Level(2)  // 介於 Info 和 Warn 之間
		LevelFatal   = slog.Level(12) // 比 Error 更高
	)

	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
		Level: LevelTrace, // 設置最低級別
	}))

	logger.Log(nil, LevelTrace, "trace message")
	logger.Log(nil, LevelNotice, "notice message")
	logger.Log(nil, LevelFatal, "fatal message")
}

總結

slog 作為 Go 官方的結構化日誌庫，用起來還是挺方便的。對於新項目，推薦直接使用 slog；對於已有項目，可以逐步遷移，slog 的 API 設計使得遷移成本很低。

後端
user avatar
0 位用戶收藏了這個故事！

發佈 評論

Some HTML is okay.