slog và log trong Golang: ghi log có cấu trúc trong Go

slog qua một ví dụ

log/slog (Go 1.21) ghi các bản ghi có cấu trúc: một thông điệp, một mức log và các thuộc tính khóa giá trị.

package main

import (
	"log/slog"
	"os"
)

func main() {
	opts := &slog.HandlerOptions{Level: slog.LevelDebug}
	logger := slog.New(slog.NewTextHandler(os.Stdout, opts))

	logger.Debug("cache lookup", "key", "user:42", "hit", false)
	logger.Info("user logged in", "user", "ada", "attempts", 1)
	logger.Warn("slow query", "table", "orders", "ms", 812)
	logger.Error("payment failed", "order", 1017, "err", "card declined")
}

Mỗi dòng xuất ra có dạng time=... level=INFO msg="user logged in" user=ada attempts=1. Vì mỗi giá trị là một trường riêng, hệ thống thu thập log (Loki, Elasticsearch, CloudWatch, Datadog) có thể lọc theo user=ada hoặc level=ERROR mà không cần biểu thức chính quy trên văn bản tự do.

Các ví dụ trên trang này ghi ra os.Stdout để đầu ra hiện đúng thứ tự. Trong một service thật, log thường đi ra os.Stderr, cũng là nơi logger mặc định ghi vào.

Mức log

Handler bỏ đi các bản ghi dưới mức tối thiểu của nó, và mức tối thiểu mặc định là Info. Đó là lý do slog.Debug(...) không in ra gì cho đến khi bạn cấu hình một handler với Level: slog.LevelDebug. Khoảng cách giữa các giá trị chừa chỗ cho các mức tự định nghĩa như slog.Level(2).

Để đổi mức log lúc chạy (từ một cờ dòng lệnh, một endpoint quản trị hay một tín hiệu), đặt một slog.LevelVar vào các tùy chọn và gọi Set trên nó sau đó:

var level slog.LevelVar // zero value: Info
logger := slog.New(slog.NewJSONHandler(os.Stderr, &slog.HandlerOptions{Level: &level}))
level.Set(slog.LevelDebug) // from now on, debug records are written

Văn bản hay JSON

slog.NewTextHandler ghi các cặp key=value, dễ đọc trong terminal. slog.NewJSONHandler ghi mỗi dòng một object JSON, định dạng mà phần lớn pipeline log mong đợi. Các lời gọi ghi log giữ nguyên; chỉ handler thay đổi.

package main

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

func main() {
	// Drop the time attribute so the output is the same on every run.
	noTime := func(groups []string, a slog.Attr) slog.Attr {
		if a.Key == slog.TimeKey && len(groups) == 0 {
			return slog.Attr{}
		}
		return a
	}

	text := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: noTime}))
	json := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: noTime}))

	for _, l := range []*slog.Logger{text, json} {
		l.Info("request served",
			"method", "GET",
			"path", "/items/7",
			"status", 200,
			"duration", 42*time.Millisecond,
		)
		l.Error("request failed", "err", errors.New("db timeout"), "retry", true)
	}
}

Các giá trị giữ nguyên kiểu: status là một số trong đầu ra JSON còn retry là boolean, một time.Duration in ra là 42ms ở dạng văn bản và là nano giây trong JSON, còn một error in ra thông điệp của nó. ReplaceAttr là điểm móc để viết lại hoặc xóa thuộc tính, ở đây dùng để bỏ dấu thời gian, còn trong thực tế thì để đổi tên khóa (msg thành message) hoặc che giá trị.

Thuộc tính

Dạng không chặt kiểu xen kẽ khóa và giá trị: "user", "ada", "attempts", 3. Nó ngắn gọn, và chỉ có một kiểu lỗi: số đối số lẻ. Giá trị bị thừa được ghi dưới khóa !BADKEY. go vet bắt được lỗi này:

./main.go:14:2: call to slog.Info missing a final value

Để an toàn kiểu và bớt cấp phát bộ nhớ một chút, hãy dùng các hàm tạo thuộc tính, và LogAttrs khi ghi log trên đường chạy nóng:

logger.Info("order placed",
	slog.Int("order_id", 1017),
	slog.String("currency", "EUR"),
	slog.Float64("total", 59.90),
	slog.Duration("took", elapsed),
)

logger.LogAttrs(ctx, slog.LevelInfo, "order placed", slog.Int("order_id", 1017))

Hãy dùng một quy ước đặt tên khóa thống nhất trong toàn bộ codebase (user_id ở mọi nơi, không phải userID ở package này và uid ở package khác). Các truy vấn trong hệ thống log phụ thuộc vào điều đó.

With: logger mang theo ngữ cảnh

logger.With(attrs...) trả về một logger mới thêm các thuộc tính đó vào mọi bản ghi. Hãy tạo một logger cho mỗi request hoặc mỗi công việc, và mọi dòng nó ghi đều có thể liên kết với nhau:

package main

import (
	"log/slog"
	"os"
)

func handleRequest(base *slog.Logger, requestID, user string) {
	log := base.With("request_id", requestID, "user", user)

	log.Info("loading cart")
	log.Info("charging card", slog.Group("payment", "amount", 25, "currency", "USD"))
	log.Warn("inventory low", "sku", "A-17", "left", 2)
}

func main() {
	noTime := func(groups []string, a slog.Attr) slog.Attr {
		if a.Key == slog.TimeKey && len(groups) == 0 {
			return slog.Attr{}
		}
		return a
	}
	base := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: noTime}))
	base = base.With("service", "checkout", "version", "1.4.2")

	handleRequest(base, "req-81", "ada")
}

Mỗi dòng đều mang service, version, request_id và user mà không cần lặp lại ở mỗi lời gọi. slog.Group lồng các thuộc tính vào nhau, handler JSON ghi chúng thành một object lồng ("payment":{"amount":25,"currency":"USD"}) còn handler văn bản ghi thành khóa có dấu chấm (payment.amount=25). logger.WithGroup("db") đặt mọi thuộc tính sau đó của logger ấy vào trong một group.

Hãy truyền logger gắn với request xuống dưới dạng tham số hoặc trường của struct. Lưu nó trong context.Context cũng được nhưng sẽ che giấu sự phụ thuộc; các phương thức InfoContext(ctx, ...) của slog truyền context cho handler, và một handler tự viết có thể dùng nó để lấy trace ID ra.

Ẩn bí mật với LogValuer

Một kiểu có thể quyết định cách nó được ghi log bằng cách triển khai slog.LogValuer. Nhờ vậy mật khẩu và token không lọt vào log, bất kể ai ghi log giá trị đó:

package main

import (
	"log/slog"
	"os"
)

type Token string

func (Token) LogValue() slog.Value {
	return slog.StringValue("REDACTED")
}

type User struct {
	ID    int
	Email string
	Token Token
}

func (u User) LogValue() slog.Value {
	return slog.GroupValue(
		slog.Int("id", u.ID),
		slog.String("email", u.Email),
	)
}

func main() {
	noTime := func(groups []string, a slog.Attr) slog.Attr {
		if a.Key == slog.TimeKey && len(groups) == 0 {
			return slog.Attr{}
		}
		return a
	}
	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{ReplaceAttr: noTime}))

	u := User{ID: 7, Email: "ada@example.com", Token: "s3cr3t"}
	logger.Info("login", "user", u)
	logger.Info("token refresh", "token", u.Token)
}

User chỉ ghi ID và email, còn một Token được ghi log riêng sẽ in ra REDACTED. Handler chỉ gọi LogValue khi bản ghi thực sự được ghi ra, nên cách này cũng hợp với những giá trị tốn kém để tính.

Package log truyền thống

log có trước slog và vẫn ổn cho các chương trình nhỏ và script. Nó ghi các dòng ra standard error với tiền tố ngày giờ:

package main

import (
	"log"
	"os"
)

func main() {
	log.SetOutput(os.Stdout) // default is os.Stderr
	log.SetFlags(0)          // no timestamp, so the output is the same every run
	log.Println("plain line")
	log.Printf("processed %d files", 12)

	log.SetFlags(log.Lshortfile)
	log.SetPrefix("[worker] ")
	log.Println("with file:line and a prefix")

	errLog := log.New(os.Stdout, "ERROR ", log.Lmsgprefix)
	errLog.Println("a separate logger with its own prefix")
}

Ba nhóm hàm thoát chương trình hoặc gây panic, và sự khác nhau rất quan trọng:

• log.Fatal, log.Fatalf, log.Fatalln in ra rồi gọi os.Exit(1). Các lời gọi defer không chạy. Hãy dùng chúng trong main cho lỗi lúc khởi động, đừng bao giờ dùng trong code thư viện hay handler của request.
• log.Panic và các hàm cùng nhóm in ra rồi gây panic, nên các lời gọi defer vẫn chạy và panic có thể được recover.
• Mọi hàm khác chỉ ghi một dòng.

Để ghi log ra tệp, hãy mở tệp rồi truyền nó cho log.New hoặc log.SetOutput; io.MultiWriter(os.Stderr, f) ghi ra cả hai.

Dùng log và slog cùng nhau

slog.SetDefault(logger) đặt logger làm mặc định cho các hàm cấp cao nhất như slog.Info, đồng thời chuyển đầu ra của package log qua nó. Khi đó, các lời gọi log.Printf có sẵn trong code của bạn hoặc trong thư viện phụ thuộc sẽ xuất ra thành bản ghi có cấu trúc ở mức Info:

slog.SetDefault(slog.New(slog.NewJSONHandler(os.Stderr, nil)))
log.Printf("legacy message") // {"time":"...","level":"INFO","msg":"legacy message"}

Trước khi gọi SetDefault, logger slog mặc định ghi qua package log, vì vậy một slog.Info("hi") đơn lẻ in ra 2026/09/23 14:30:00 INFO hi.

Quy tắc thực tế

• Ghi log hoặc trả về lỗi, đừng làm cả hai. Một hàm vừa ghi log lỗi vừa trả nó về sẽ khiến cùng một lỗi được ghi ở mọi tầng của call stack. Hãy trả lỗi lên trên kèm ngữ cảnh, và ghi log một lần ở nơi xử lý nó.
• Đặt dữ liệu thay đổi vào thuộc tính, không đặt vào thông điệp. logger.Info("user created", "user_id", id) gom nhóm tốt trong hệ thống log; logger.Info(fmt.Sprintf("user %d created", id)) tạo ra một thông điệp khác nhau cho mỗi người dùng.
• Đừng bao giờ ghi log bí mật hay toàn bộ body của request. Hãy dùng LogValuer hoặc ReplaceAttr để che đi.
• Dùng JSON trên production, văn bản khi phát triển. Chọn handler lúc khởi động dựa vào một cờ hoặc một biến môi trường.
• Chọn mức log có chủ đích. Nếu mọi thứ đều được ghi ở mức Error, cảnh báo về lỗi sẽ trở thành nhiễu.