README
¶
slog
slog 是一个高性能、功能丰富的 Go 语言日志库，基于 Go 1.21+ 的官方 log/slog 包进行扩展。它提供了更灵活的日志级别控制、彩色输出、结构化日志记录、日志脱敏等高级特性。
特性
- 支持多种日志级别（Trace、Debug、Info、Warn、Error、Fatal）
- 支持同时输出文本和 JSON 格式
- 支持彩色日志输出
- 支持动态调整日志级别
- 支持日志分组和模块化
- 支持结构化字段记录
- 支持日志脱敏处理
- 高性能缓冲设计
- 线程安全
- 支持自定义格式化
安装
go get github.com/darkit/slog
快速开始
package main
import (
"os"
"github.com/darkit/slog"
)
func main() {
// 创建默认logger
logger := slog.NewLogger(os.Stdout, false, false)
// 基础日志记录
logger.Info("Hello Slog!")
// 带结构化字段的日志
logger.Info("User logged in",
"user_id", 123,
"action", "login",
)
}
核心功能使用
1. 日志级别控制
// 设置全局日志级别
slog.SetLevelDebug() // Debug级别
slog.SetLevelInfo() // Info级别
slog.SetLevelWarn() // Warn级别
slog.SetLevelError() // Error级别
slog.SetLevelFatal() // Fatal级别
slog.SetLevelTrace() // Trace级别
// 动态更新日志级别
slog.UpdateLogLevel("debug") // 使用字符串
slog.UpdateLogLevel(slog.LevelDebug) // 使用Level类型
slog.UpdateLogLevel(-4) // 使用数字
// 监听日志级别变化
slog.WatchLevel("observer1", func(level slog.Level) {
fmt.Printf("Log level changed to: %v\n", level)
})
// 取消监听
slog.UnwatchLevel("observer1")
2. 日志记录方法
// 不同级别的日志记录
logger.Trace("Trace message")
logger.Debug("Debug message")
logger.Info("Info message")
logger.Warn("Warning message")
logger.Error("Error message")
logger.Fatal("Fatal message") // 会导致程序退出
// 格式化日志
logger.Debugf("User %s logged in from %s", username, ip)
logger.Infof("Process took %d ms", time)
logger.Warnf("High CPU usage: %.2f%%", cpuUsage)
logger.Errorf("Failed to connect: %v", err)
logger.Fatalf("Critical error: %v", err)
// 带结构化字段的日志
logger.Info("Database connection established",
"host", "localhost",
"port", 5432,
"user", "admin",
)
3. 日志分组和模块
// 创建模块化日志记录器
userLogger := slog.Default("user")
authLogger := slog.Default("auth")
// 使用分组
logger := slog.WithGroup("api")
logger.Info("Request received",
"method", "GET",
"path", "/users",
)
// 链式调用
logger.With("request_id", "123").
WithGroup("auth").
Info("User authenticated")
4. 输出格式控制
// 启用/禁用文本日志
slog.EnableTextLogger()
slog.DisableTextLogger()
// 启用/禁用JSON日志
slog.EnableJsonLogger()
slog.DisableJsonLogger()
// 创建带颜色的控制台日志
logger := slog.NewLogger(os.Stdout, false, true) // 最后一个参数控制是否显示源代码位置
5. 日志脱敏
// 启用日志脱敏
slog.EnableDLPLogger()
// 禁用日志脱敏功能
slog.DisableDLPLogger()
// 使用脱敏日志
logger.Info("User data",
"credit_card", "1234-5678-9012-3456", // 将被自动脱敏
"phone", "13800138000", // 将被自动脱敏
)
6. 高级功能
// 获取日志记录通道
recordChan := slog.GetChanRecord(1000) // 指定缓冲大小
// 自定义属性
logger.With(
slog.String("app", "myapp"),
slog.Int("version", 1),
slog.Time("start_time", time.Now()),
).Info("Application started")
// 获取原始slog.Logger
slogLogger := logger.GetSlogLogger()
日志文件管理
slog 提供了日志文件管理功能，支持日志文件的自动轮转、压缩和清理。
基础用法
// 创建日志文件写入器
writer := slog.NewWriter("logs/app.log")
// 创建日志记录器
logger := slog.NewLogger(writer, false, false)
// 开始记录日志
logger.Info("Application started")
文件写入器配置
writer := slog.NewWriter("logs/app.log").
SetMaxSize(100). // 设置单个文件最大为100MB
SetMaxAge(7). // 保留7天的日志
SetMaxBackups(10). // 最多保留10个备份
SetLocalTime(true). // 使用本地时间
SetCompress(true) // 压缩旧日志文件
文件写入器特性
- 自动轮转: 当日志文件达到指定大小时自动创建新文件
- 时间戳备份: 备份文件名格式为
原文件名-时间戳.扩展名 - 自动压缩: 可选择自动压缩旧的日志文件
- 自动清理: 支持按时间和数量清理旧日志
- 目录管理: 自动创建日志目录结构
- 错误处理: 优雅处理文件操作错误
配置选项
| 方法 | 默认值 | 描述 |
|---|---|---|
SetMaxSize(size int) |
100 | 单个日志文件的最大大小（MB） |
SetMaxAge(days int) |
30 | 日志文件保留的最大天数 |
SetMaxBackups(count int) |
30 | 保留的最大备份文件数 |
SetLocalTime(local bool) |
true | 是否使用本地时间 |
SetCompress(compress bool) |
true | 是否压缩旧日志文件 |
文件命名规则
- 当前日志文件:
app.log - 备份文件:
app-2024-03-20T15-04-05.log - 压缩文件:
app-2024-03-20T15-04-05.log.gz
目录结构示例
logs/
├── app.log # 当前日志文件
├── app-2024-03-20T15-04-05.log # 未压缩的备份
└── app-2024-03-19T15-04-05.log.gz # 压缩的备份
方法列表
全局方法
| 方法 | 描述 |
|---|---|
NewLogger(w io.Writer, noColor, addSource bool) Logger |
创建新的日志记录器 |
Default(modules ...string) *Logger |
获取带模块名的默认日志记录器 |
SetLevel{Level}() |
设置全局日志级别（Level可以是Trace/Debug/Info/Warn/Error/Fatal） |
UpdateLogLevel(level interface{}) error |
动态更新日志级别 |
WatchLevel(name string, callback func(Level)) |
监听日志级别变化 |
UnwatchLevel(name string) |
取消日志级别监听 |
EnableTextLogger() |
启用文本日志输出 |
DisableTextLogger() |
禁用文本日志输出 |
EnableJsonLogger() |
启用JSON日志输出 |
DisableJsonLogger() |
禁用JSON日志输出 |
EnableFormatters(formatters ...formatter.Formatter) |
启用日志格式化器 |
Logger方法
| 方法 | 描述 |
|---|---|
Debug/Info/Warn/Error/Fatal/Trace(msg string, args ...any) |
记录不同级别的日志 |
Debugf/Infof/Warnf/Errorf/Fatalf/Tracef(format string, args ...any) |
记录格式化的日志 |
With(args ...any) *Logger |
创建带有额外字段的日志记录器 |
WithGroup(name string) *Logger |
创建带有分组的日志记录器 |
GetLevel() Level |
获取当前日志级别 |
SetLevel(level Level) *Logger |
设置当前记录器的日志级别 |
GetSlogLogger() *slog.Logger |
获取原始的slog.Logger |
性能优化
该库在设计时特别注意了性能优化：
- 使用 buffer pool 减少内存分配
- 支持小对象优化
- 异步日志记录支持
- 高效的级别过滤
- 原子操作保证线程安全
贡献
欢迎提交 Issue 和 Pull Request。
许可证
MIT License
Documentation
¶
Index ¶
- Constants
- Variables
- func Debug(msg string, args ...any)
- func Debugf(format string, args ...any)
- func DisableDLPLogger()
- func DisableJsonLogger()
- func DisableTextLogger()
- func EnableDLPLogger()
- func EnableFormatters(formatters ...formatter.Formatter)
- func EnableJsonLogger()
- func EnableTextLogger()
- func Error(msg string, args ...any)
- func Errorf(format string, args ...any)
- func Fatal(msg string, args ...any)
- func Fatalf(format string, args ...any)
- func GetChanRecord(num ...uint16) chan slog.Record
- func GetSlogLogger() *slog.Logger
- func Info(msg string, args ...any)
- func Infof(format string, args ...any)
- func IsDLPEnabled() bool
- func New(handler Handler) *slog.Logger
- func NewConsoleHandler(w io.Writer, noColor bool, opts *slog.HandlerOptions) slog.Handler
- func NewJSONHandler(w io.Writer, opts *HandlerOptions) *slog.JSONHandler
- func NewOptions(options *slog.HandlerOptions) *slog.HandlerOptions
- func NewTextHandler(w io.Writer, opts *HandlerOptions) *slog.TextHandler
- func NewWriter(filename ...string) *writer
- func Printf(format string, args ...any)
- func Println(msg string, args ...any)
- func SetLevelDebug()
- func SetLevelError()
- func SetLevelFatal()
- func SetLevelInfo()
- func SetLevelTrace()
- func SetLevelWarn()
- func Trace(msg string, args ...any)
- func Tracef(format string, args ...any)
- func Warn(msg string, args ...any)
- func Warnf(format string, args ...any)
- type Attr
- func Any(key string, v any) Attr
- func Bool(key string, v bool) Attr
- func Duration(key string, v time.Duration) Attr
- func Float64(key string, v float64) Attr
- func Group(key string, args ...any) Attr
- func Int(key string, v int) Attr
- func Int64(key string, v int64) Attr
- func String(key string, v string) Attr
- func Time(key string, v time.Time) Attr
- func Uint64(key string, v uint64) Attr
- type Fields
- type Handler
- type HandlerOptions
- type Level
- type Logger
- func (l *Logger) Debug(msg string, args ...any)
- func (l *Logger) Debugf(format string, args ...any)
- func (l *Logger) Error(msg string, args ...any)
- func (l *Logger) Errorf(format string, args ...any)
- func (l *Logger) Fatal(msg string, args ...any)
- func (l *Logger) Fatalf(format string, args ...any)
- func (l *Logger) GetLevel() Level
- func (l *Logger) GetSlogLogger() *slog.Logger
- func (l *Logger) Info(msg string, args ...any)
- func (l *Logger) Infof(format string, args ...any)
- func (l *Logger) Printf(format string, args ...any)
- func (l *Logger) Println(msg string, args ...any)
- func (l *Logger) SetLevel(level Level) *Logger
- func (l *Logger) Trace(msg string, args ...any)
- func (l *Logger) Tracef(format string, args ...any)
- func (l *Logger) Warn(msg string, args ...any)
- func (l *Logger) Warnf(format string, args ...any)
- func (l *Logger) With(args ...any) *Logger
- func (l *Logger) WithContext(ctx context.Context) *Logger
- func (l *Logger) WithGroup(name string) *Logger
- func (l *Logger) WithValue(key string, val any) *Logger
- type Record
- type Value
Constants ¶
View Source
const ( TimeKey = slog.TimeKey LevelKey = slog.LevelKey MessageKey = slog.MessageKey SourceKey = slog.SourceKey )
View Source
const ( Name = "slog" Version = "v0.0.21" )
Variables ¶
View Source
var (
TimeFormat = "2006/01/02 15:04.05.000" // 默认时间格式
)
Functions ¶
func EnableFormatters ¶ added in v0.0.16
EnableFormatters 启用日志格式化器。
func GetChanRecord ¶ added in v0.0.15
GetChanRecord 使用通道获取日志信息
func GetSlogLogger ¶ added in v0.0.16
GetSlogLogger 返回原始log/slog的日志记录器
func NewConsoleHandler ¶ added in v0.0.2
NewConsoleHandler returns a log/slog.Handler using the receiver's options. Default options are used if opts is nil.
func NewJSONHandler ¶ added in v0.0.2
func NewJSONHandler(w io.Writer, opts *HandlerOptions) *slog.JSONHandler
func NewOptions ¶ added in v0.0.2
func NewOptions(options *slog.HandlerOptions) *slog.HandlerOptions
NewOptions 创建新的处理程序选项。
func NewTextHandler ¶ added in v0.0.2
func NewTextHandler(w io.Writer, opts *HandlerOptions) *slog.TextHandler
Types ¶
type Fields ¶ added in v0.0.18
type Fields struct {
// contains filtered or unexported fields
}
Fields 存储上下文字段
type HandlerOptions ¶ added in v0.0.2
type HandlerOptions = slog.HandlerOptions
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger 结构体定义，实现日志记录功能
func WithGroup ¶ added in v0.0.11
WithGroup 创建一个带有指定组名的全局日志记录器 这是一个包级别的便捷方法 参数:
- name: 日志组的名称
返回:
- 带有指定组名的新日志记录器实例
func (*Logger) GetSlogLogger ¶ added in v0.0.16
GetSlogLogger 方法
func (*Logger) WithContext ¶ added in v0.0.7
WithContext 使用给定的上下文
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.