slog设计
为实现其目的,slog 的设计具有高度灵活性。它支持结构化日志,能以 JSON 或其他格式输出日志,以便后续分析和处理。出色的模块化设计将日志功能分为多个组件,如日志级别管理、输出格式化、日志传输等,每个组件都可以独立配置和替换。其异步处理支持机制可确保日志操作不会阻碍主应用程序的执行。
// Logger contains all actions against a Log message
type Logger struct {
New(h Handler) *Logger
Debug(msg string, args ...any)
Error(msg string, args ...any)
Info(msg string, args ...any)
//...
With(args ...any) *Logger
}
// Handler defines how to
type Handler interface {
Handle(context.Context, Record) error
WithAttrs(attrs []Attr) Handler
WithGroup(name string) Handler
}
// Record defines a Log message with many info。
type Record struct {
Time time.Time
Message string
Level Level
PC uintptr
}
三个组件完成了整个流程。
Logger负责所有日志打印操作。Handler定义日志输出格式,默认实现为 TextHandler 和 JSONHandler。Record定义日志的详细信息,如时间、级别等。这些接口不仅能以多种方式扩展 slog(如添加新的处理程序),还能满足不同日志框架的需求和配置。
slog用法
slog 的基本用法与 zap 或 Golang 的其他第三方日志框架类似。
1.日志打印
func main() {
slog.Info("This is an informational message.")
slog.Warn("This is a warning message with context.", slog.String("user", "slaise"))
slog.Error("This is an error message with details.", slog.Int("code", 123))
}
// output(go-playground) https://go.dev/play/p/TLIur7rZFhi
2009/11/10 23:00:00 INFO This is an informational message.
2009/11/10 23:00:00 WARN This is a warning message with context. user=slaise
2009/11/10 23:00:00 ERROR This is an error message with details. code=123
slog 为不同级别的日志提供了不同的打印方式和相应的参数类型转换。
2.Handler
通过下面的代码,我们可以将默认打印方式修改为内置的 TextHandler 或 JSONHandler。
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
// logger.Info/Debug/Error
请看输出结果。
// JSONHandler
func main() {
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
logger.Info("This is an informational message.")
logger.Warn("This is a warning message with context.", slog.String("user", "slaise"))
logger.Error("This is an error message with details.", slog.Int("code", 123))
}
// Output: https://go.dev/play/p/oCubHk77Sjw
{"time":"2009-11-10T23:00:00Z","level":"INFO","msg":"This is an informational message."}
{"time":"2009-11-10T23:00:00Z","level":"WARN","msg":"This is a warning message with context.","user":"slaise"}
{"time":"2009-11-10T23:00:00Z","level":"ERROR","msg":"This is an error message with details.","code":123}
// TextHandler
logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
// Output: https://go.dev/play/p/ewil9ziZpsk
time=2009-11-10T23:00:00.000Z level=INFO msg="This is an informational message."
time=2009-11-10T23:00:00.000Z level=WARN msg="This is a warning message with context." user=slaise
time=2009-11-10T23:00:00.000Z level=ERROR msg="This is an error message with details." code=123
可以通过 SetDefault[5] 方法创建 Logger 来替换 slog 中的默认 Logger,默认 slog.Info 和 slog.Debug 的 Logger 也将同时被修改。
func main() {
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
slog.SetDefault(logger)
slog.Info("This is an informational message.")
slog.Warn("This is a warning message with context.", slog.String("user", "slaise"))
slog.Error("This is an error message with details.", slog.Int("code", 123))
}
//output
{"time":"2009-11-10T23:00:00Z","level":"INFO","msg":"This is an informational message."}
{"time":"2009-11-10T23:00:00Z","level":"WARN","msg":"This is a warning message with context.","user":"slaise"}
{"time":"2009-11-10T23:00:00Z","level":"ERROR","msg":"This is an error message with details.","code":123}
3.消息处理
对 Record 和 attr 的处理是 slog 核心功能的一部分。每条日志记录都由时间、级别、消息等参数和一组键值对组成。处理这些参数的 API 提供了灵活性。使用 With 方法,用户可以轻松添加固定属性,这些属性将出现在该日志记录器生成的每条日志记录中。通过 Group 方法,用户可以汇总多个属性,进行统一处理。请看下面的示例。
func main() {
logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
// Build a group
attrGroup := slog.Group("ops", slog.String("module", "authentication"), slog.String("method", "login"))
logger.Info("User login attempt",
slog.String("service", "login-service"),
slog.String("version", "1.0.2"),
slog.String("status", "attempting"),
attrGroup,
)
// login failed
// failed, err := login(user, pass)
err := errors.New("login password err")
if err != nil {
// error can only be printed with slog.Any
logger.Error("User login failed",
slog.String("service", "login-service"),
slog.String("version", "1.0.2"),
slog.Any("error", err)) //output: service=login-service version=1.0.2 error="login password err
}
}
Attr[6] 提供了在 slog 中处理参数的主要 API,例如上例中的 slog.String 和 slog.Any,以及 slog.Bool[7]、slog.Int[8]、slog.Float64[9]、slog.Duration[10]、slog.Time[11]等。
Level 通过实现 Leveler[12] 接口的 Level() 为 slog 提供默认日志级别设置。
const (
LevelDebug Level = -4
LevelInfo Level = 0
LevelWarn Level = 4
LevelError Level = 8
)
func (l Level) Level() Level { return l }
日志应用本地机器的默认时区设置,但也可以使用 slog.Time 添加特定时间到日志中。
loc, err := time.LoadLocation("America/New_York")
currentTime := time.Now().In(loc)
slog.Info("Log message with NewYork timezone",
slog.Time("time", currentTime),
)
不过,如果我们需要在不同于本地机器的时区打印日志,就需要自定义处理程序,因为 slog 软件包缺少用于全局修改的默认 API。
4.上下文处理
可以通过两种方式将上下文添加到日志记录中。
- 通过在日志处理中加入 context.Context,可以在函数和goroutine之间传递上下文信息。
- Logger 提供了带context的日志打印方法,如 DebugContext[13]、InfoContext[14]、WarnContext[15] 和 ErrorContext[16]。context.Context 被添加到之前的方法参数列表中,并将 ctx 放在首位,这符合上下文的使用原则。
func (l *Logger) DebugContext(ctx context.Context, msg string, args ...any)
但如果直接使用这些方法将context中的参数添加到日志中,就会像我一样感到困惑,因为这样做是行不通的。例如,在以下代码中,userId 不会显示在日志中。
func main() {
ctx := context.WithValue(context.Background(), "userId", "123")
slog.InfoContext(ctx, "reset password", slog.Time("time", time.Now()))
}
// output
2009/11/10 23:00:00 INFO reset password time=2009-11-10T23:00:00.000Z
阅读源代码后,你会惊讶的发现,默认 defaultHandler 只打印消息和参数列表,却不处理传入的 ctx。
func (h *defaultHandler) Handle(ctx context.Context, r Record) error {
buf := buffer.New()
buf.WriteString(r.Level.String())
buf.WriteByte(' ')
buf.WriteString(r.Message)
state := h.ch.newHandleState(buf, true, " ")
defer state.free()
state.appendNonBuiltIns(r)
return h.output(r.PC, *buf)
}
go 1.21 中正式发布的 slog 只提供了相关 API 而没有提供实现,因此需要定制处理程序来实现相关功能。
可通过父日志记录器构建具有层次关系的日志记录器,这些日志记录器继承并扩展了基本日志记录功能
例如,在前面的With和Group示例中,在打印 Info 和 Error 日志的过程中重复传递了服务和版本信息,而日志程序的继承功能可以简化这一过程。
// Define a new Logger with service & service info
logger = slog.With(logger, slog.String("service", "login-service"), slog.String("version", "1.0.2"))
// Print logs
logger.Info("User login attempt",
slog.String("status", "attempting"),
attrGroup,
)
slog定制
Slog 的设计非常灵活,便于定制日志。
自定义日志级别
与官方 LogLevel 一样,可以通过实现 Logeler 接口来定制 LogLevel,而 slog.Level 本身也会返回 Level 类型。
const (
LevelTrace = slog.Level(-99)
LevelFatal = slog.Level(99)
)
func main() {
ctx := context.Background()
// This will be hidden because default Log level is above trace
slog.Log(ctx, LevelTrace, "Trace message")
slog.Log(ctx, LevelFatal, "Fatal level")
}
// output
2009/11/10 23:00:00 ERROR+91 Fatal level
跟踪级别日志在未修改相应HandlerOptions时是隐藏的,可通过修改默认日志级别打开。
slog.SetLogLoggerLevel(LevelTrace)
自定义HandlerOptions HandlerOptions[17]提供三种修改日志的方法。
- 显示源代码。使用 AddSource:true,可以在日志中添加文件、行号和方法名称等信息。
- 修改日志级别。LevelTrace 的作用与上述 SetLogLoggerLevel 相同。
- 定义 ReplaceAttr 可调用函数,用于修改日志中的 Attr 键值对。
对于缺少默认格式化支持的错误,可以通过实现 ReplaceAttr 来加以改进。
func replaceAttr(_ []string, a slog.Attr) slog.Attr {
switch a.Value.Kind() {
case slog.KindAny:
switch v := a.Value.Any().(type) {
case error:
a.Value = fmtErr(v) // provide error log format
}
}
return a
}
自定义Handler 自定义日志的最后一种方法是实现自己的Handler。下面的 ContextHandler 提供了将上下文中的参数整合到日志中的功能。
const (
UserId string = "userId"
)
type ContextHandler struct {
slog.Handler
}
func (h ContextHandler) Handle(ctx context.Context, r slog.Record) error {
if id, ok := ctx.Value(UserId).(string); ok {
r.AddAttrs(slog.String(UserId, id))
}
return h.Handler.Handle(ctx, r)
}
func main() {
ctxHandler := &ContextHandler{slog.NewJSONHandler(os.Stdout, nil)}
logger := slog.New(ctxHandler)
ctx := context.WithValue(context.Background(), "userId", "123")
logger.InfoContext(ctx, "User ops", slog.String("op", "login"))
}
//output
{"time":"2009-11-10T23:00:00Z","level":"INFO","msg":"User ops","op":"login","userId":"123"}
性能
slog 支持通过延迟计算优化参数处理,只在实际需要日志信息时才执行参数的高性能字符串操作,以减少不必要的性能开销。
在默认日志方法中,只打印默认级别以上的日志。Attrs 将被添加到打印前创建的Record中。
func (l *Logger) log(ctx context.Context, level Level, msg string, args ...any) {
if !l.Enabled(ctx, level) {
return
}
var pc uintptr
if !internal.IgnorePC {
var pcs [1]uintptr
// skip [runtime.Callers, this function, this function's caller]
runtime.Callers(3, pcs[:])
pc = pcs[0]
}
r := NewRecord(time.Now(), level, msg, pc)
r.Add(args...)
if ctx == nil {
ctx = context.Background()
}
_ = l.Handler().Handle(ctx, r)
}
slog 利用内置 buffer.go[18] 中的对象池技术重复使用日志条目对象,减少了内存应用和释放以及垃圾回收的频率,从而提高了应用性能。
slog实践
到目前为止,我们已经做好了在项目中使用slog的准备,但要牢记以下几点。
(1) 对敏感数据脱敏
数据安全在日志处理中至关重要。在将对象对象打印到日志时,应及时屏蔽或模糊敏感信息,以避免数据泄漏,这可以通过相应结构体中的 LogValue 接口来实现。下面我们来看一个包含电子邮件和密码的用户类型示例。
type User struct {
ID string `json:"id"`
Email string `json:"email"`
Password string `json:"password"`
}
func (u User) LogValue() slog.Value {
return slog.StringValue(u.ID)
}
func main() {
h := slog.NewJSONHandler(os.Stdout, nil)
logger := slog.New(h)
u := &User{
ID: "1",
Email: "slaise@gmail.com",
Password: "111111",
}
logger.Info("info", "user", u)
}
// output
{"time":"2009-11-10T23:00:00Z","level":"INFO","msg":"info","user":"1"}
(2) 将slog级别提取为配置项,并为不同环境配置不同级别
项目通常部署在多个环境中,如 dev、staging、prod 等。通过将日志级别提取为环境参数,并通过 Kubernetes 的 configMap 注入,可以在不同环境中应用不同日志级别,从而减少开销。
(3) 处理上下文信息
上例中的上下文实现是一个明智的选择,可以通过优化来动态加载上下文参数列表。在我们实现的代码及许多第三方日志框架中,Context 被广泛用于传递上下文信息,从而简化了从第三方库升级到 slog 的过程。
(4) 正确配置日志输出目的地
根据需要配置日志输出,如输出到控制台、文件、网络服务等,或输出到多个输出目的地,以确保日志的可靠存储。
通过自定义处理程序的写入器,可以轻松修改日志输出地址。
file, err := os.OpenFile("app.log", os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0666)
if err != nil {
panic("cannot open log file: " + err.Error())
}
defer file.Close()
logger := slog.New(slog.JSONHandler(file))
升级第三方库
活跃的Golang社区有许多为 slog 定制的升级框架,以下是一些常用框架:
- slog-multi[19]:处理器链,如流水线、路由器、扇出等。
- slog-sampling[20]:丢弃重复的日志条目。
- slog-shim[21] 为 1.21 以下的 Go 版本提供向后兼容的 slog 支持。
- sloggen[22] 生成各种辅助工具。
- sloglint[23] 可确保代码的一致性。
结论
slog 软件包为管理应用程序日志提供了强大而灵活的解决方案。其设计确保了高性能和多功能性,使开发人员能够自定义日志级别、Handler配置以及Handler本身。使用 slog 不仅能加强消息处理和上下文信息集成,还能简化日志记录流程。为了有效实施,仔细考虑自定义日志级别和Handler以满足特定项目要求至关重要。通过明智利用 slog 的功能,开发人员可以显著提高日志实践的效率和清晰度,确保代码具有更好的可维护性和可读性。
参考资料:
- [1]Explore the Go slog Standard Library: Design and Usage: https://blog.stackademic.com/explore-the-go-slog-standard-library-design-and-usage-6baf14c03299
- [2]Go1.21: https://tip.golang.org/doc/go1.21#slog
- [3]log/slog: https://pkg.go.dev/log/slog
- [4]structured, leveled logging #54763: https://github.com/golang/go/discussions/54763
- [5]SetDefault: https://pkg.go.dev/log/slog#SetDefault
- [6]Attr: https://pkg.go.dev/log/slog#Attr
- [7]slog.Bool: https://pkg.go.dev/log/slog#Bool
- [8]slog.Int: https://pkg.go.dev/log/slog#Int
- [9]slog.Float64: https://pkg.go.dev/log/slog#Float64
- [10]slog.Duration: https://pkg.go.dev/log/slog#Duration
- [11]slog.Time: https://pkg.go.dev/log/slog#Time
- [12]Leveler: https://pkg.go.dev/log/slog#Leveler
- [13]DebugContext: https://pkg.go.dev/log/slog#Logger.DebugContext
- [14]InfoContext: https://pkg.go.dev/log/slog#Logger.InfoContext
- [15]WarnContext: https://pkg.go.dev/log/slog#Logger.WarnContext
- [16]ErrorContext: https://pkg.go.dev/log/slog#Logger.ErrorContext
- [17]HandlerOptions: https://pkg.go.dev/log/slog#HandlerOptions
- [18]buffer.go: https://cs.opensource.google/go/go/+/master:src/log/slog/internal/buffer/buffer.go;bpv=0;bpt=1
- [19]slog-multi: https://github.com/samber/slog-multi
- [20]slog-sampling: https://github.com/samber/slog-sampling
- [21]slog-shim: https://github.com/sagikazarmark/slog-shim
- [22]sloggen: https://github.com/go-simpler/sloggen
- [23]sloglint: https://github.com/go-simpler/sloglint