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)
// 获取原始的 slog.Logger
slogLogger := logger.GetSlogLogger()
// 现在可以直接使用原始的 slog.Logger
slogLogger.Info("使用原始slog记录日志")
// 基础日志记录
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级别
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. 日志订阅机制
// 订阅日志记录
ch, cancel := slog.Subscribe(1000) // 指定缓冲大小
defer cancel() // 确保取消订阅
// 处理订阅的日志
go func() {
for record := range ch {
fmt.Printf("收到日志: %s [%s] %s\n",
record.Time.Format(slog.TimeFormat),
record.Level,
record.Message,
)
}
}()
// 多订阅者模式
ch1, cancel1 := slog.Subscribe(500)
defer cancel1()
ch2, cancel2 := slog.Subscribe(1000)
defer cancel2()
// 不同订阅者可以独立处理日志
go func() {
for record := range ch1 {
// 处理所有日志
fmt.Printf("订阅者1: %v\n", record)
}
}()
go func() {
for record := range ch2 {
// 只处理错误日志
if record.Level >= slog.LevelError {
fmt.Printf("订阅者2 - 错误: %v\n", record)
}
}
}()
订阅特性：
- 支持多个订阅者
- 独立的缓冲区大小控制
- 自动资源清理
- 无阻塞设计
- 支持选择性处理
日志文件管理
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） |
WatchLevel(name string, callback func(Level)) |
监听日志级别变化 |
UnwatchLevel(name string) |
取消日志级别监听 |
EnableTextLogger() |
启用文本日志输出 |
DisableTextLogger() |
禁用文本日志输出 |
EnableJsonLogger() |
启用JSON日志输出 |
DisableJsonLogger() |
禁用JSON日志输出 |
EnableFormatters(formatters ...formatter.Formatter) |
启用日志格式化器 |
Subscribe(size uint16) (<-chan slog.Record, func()) |
订阅日志记录，返回只读channel和取消函数 |
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 Countdown(msg string, seconds int)
- func Debug(msg string, args ...any)
- func Debugf(format string, args ...any)
- func DisableDLPLogger()
- func DisableJsonLogger()
- func DisableTextLogger()
- func Dynamic(msg string, frames int, interval int)
- 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 GetSlogLogger() *slog.Logger
- func Info(msg string, args ...any)
- func Infof(format string, args ...any)
- func IsDLPEnabled() bool
- func Loading(msg string, seconds int)
- 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 Progress(msg string, durationMs int)
- func SetLevel(level any) error
- func SetLevelDebug()
- func SetLevelError()
- func SetLevelFatal()
- func SetLevelInfo()
- func SetLevelTrace()
- func SetLevelWarn()
- func Subscribe(size uint16) (<-chan slog.Record, context.CancelFunc)
- 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) Countdown(msg string, seconds int)
- func (l *Logger) Debug(msg string, args ...any)
- func (l *Logger) Debugf(format string, args ...any)
- func (l *Logger) Dynamic(msg string, frames int, interval int)
- 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) Loading(msg string, seconds int)
- func (l *Logger) Printf(format string, args ...any)
- func (l *Logger) Println(msg string, args ...any)
- func (l *Logger) Progress(msg string, durationMs int)
- func (l *Logger) SetLevel(level any) *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) WithDeadline(d time.Time) (*Logger, context.CancelFunc)
- func (l *Logger) WithGroup(name string) *Logger
- func (l *Logger) WithTimeout(timeout time.Duration) (*Logger, context.CancelFunc)
- func (l *Logger) WithValue(key string, val interface{}) *Logger
- type Record
- type Subscriber
- 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 Dynamic ¶ added in v0.0.23
Dynamic 动态输出带点号动画效果
- msg: 要显示的消息内容
- frames: 动画更新的总帧数
- interval: 每次更新的时间间隔(毫秒)
func EnableFormatters ¶ added in v0.0.16
EnableFormatters 启用日志格式化器。
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
func NewWriter ¶ added in v0.0.19
func NewWriter(filename ...string) *writer
NewWriter 创建一个新的日志写入器,支持指定一个或多个文件路径,多个路径时使用第一个有效路径 filename: 日志文件路径 默认配置:
- 单个文件最大 100MB
- 保留最近 30 天的日志
- 最多保留 30 个备份文件
- 使用本地时间
- 不压缩旧文件
func SetLevel ¶ added in v0.0.23
SetLevel 动态更新日志级别 level 可以是数字(-8, -4, 0, 4, 8, 12)或字符串(trace, debug, info, warn, error, fatal)
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) Dynamic ¶ added in v0.0.23
Dynamic 动态输出带点号动画效果
- msg: 要显示的消息内容
- frames: 动画更新的总帧数
- interval: 每次更新的时间间隔(毫秒)
func (*Logger) GetSlogLogger ¶ added in v0.0.16
GetSlogLogger 方法
func (*Logger) Progress ¶ added in v0.0.23
Progress 显示进度百分比
- msg: 要显示的消息内容
- durationMs: 从0%到100%的总持续时间(毫秒)
func (*Logger) WithContext ¶ added in v0.0.7
WithContext 创建带有上下文的新Logger
func (*Logger) WithDeadline ¶ added in v0.0.23
WithDeadline 创建带截止时间的Logger
func (*Logger) WithTimeout ¶ added in v0.0.23
WithTimeout 创建带超时的Logger
type Subscriber ¶ added in v0.0.23
type Subscriber struct {
// contains filtered or unexported fields
}
Subscriber 订阅者结构
Source Files
¶
Directories
Click to show internal directories.
Click to hide internal directories.