golang lumberjack 日志包

Lumberjack是一个用于 Go 语言的日志轮换（log rotation）库，通常与标准库log或其他第三方日志框架（如logrus、zap` 等）结合使用。它的核心功能是自动管理日志文件的切割、备份和清理，避免日志文件无限增长占用磁盘空间。

---

核心功能

1. 按大小切割日志
   当单个日志文件大小超过设定阈值（如 100MB）时，自动创建新文件，旧文件按时间戳重命名备份。

2. 按时间保留日志
   支持设置日志文件的最大保留时间（如保留最近 7 天的日志），超时文件自动删除。

3. 限制备份数量
   可设置最大备份文件数（如最多保留 5 个备份），超出数量时删除最旧的日志。

4. 线程安全
   支持并发写入，适用于高并发场景。

---

使用场景

• 长期运行的服务（如 Web 服务器、后台任务）。
• 需要自动化管理日志文件的场景。
• 与标准库 log 或第三方日志库（如 zap、logrus）集成。

---

基本用法

1. 安装

go get github.com/natefinch/lumberjack

2. 与标准库 log 集成

import (
    \"log\"
    \"github.com/natefinch/lumberjack\"
)

func main() {
    // 配置 Lumberjack
    logger := &lumberjack.Logger{
        Filename:   \"app.log\",     // 日志文件名
        MaxSize:    100,           // 单文件最大大小（MB）
        MaxBackups: 5,             // 保留的旧日志文件最大数量
        MaxAge:     7,             // 保留天数（基于文件名中的时间戳）
        Compress:   true,          // 是否压缩备份文件（默认 false）
    }
    defer logger.Close()

    // 设置标准库的日志输出到 Lumberjack
    log.SetOutput(logger)

    // 示例日志输出
    log.Println(\"This is a log message.\")
}

3. 与 zap 集成

import (
    \"go.uber.org/zap\"
    \"go.uber.org/zap/zapcore\"
    \"github.com/natefinch/lumberjack\"
)

func main() {
    // 配置 Lumberjack
    lumberjackLogger := &lumberjack.Logger{
        Filename:   \"app.log\",
        MaxSize:    100,
        MaxBackups: 5,
        MaxAge:     7,
        Compress:   true,
    }

    // 创建 zap 的 WriteSyncer
    zapEncoder := zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig())
    core := zapcore.NewCore(zapEncoder, zapcore.AddSync(lumberjackLogger), zap.InfoLevel)
    logger := zap.New(core)
    defer logger.Sync()

    // 示例日志输出
    logger.Info(\"This is a structured log message.\")
}

---

配置参数

参数	说明
Filename	日志文件名（如 app.log）。
MaxSize	单文件最大大小（单位：MB），默认 100。
MaxBackups	保留的旧日志文件最大数量，默认全保留。
MaxAge	日志文件最大保留天数（基于文件名时间戳），默认不删除。
Compress	是否压缩备份文件（.gz 格式），默认 false。
LocalTime	使用本地时间命名备份文件（默认使用 UTC 时间）。

---

优点

• 轻量易用：无需复杂配置，适合快速集成。
• 兼容性强：支持与大多数日志库协作。
• 自动化管理：无需手动干预日志切割和清理。

---

注意事项

1. 文件权限
   确保程序对日志目录有读写权限。
2. 时间同步
   如果使用 MaxAge，需确保服务器时间准确。
3. 性能影响
   压缩备份文件（Compress: true）可能增加 CPU 开销。

---

常见问题

• 日志不立即切割？
  Lumberjack 在每次写入时检查文件大小，确保写入后才会触发切割。
• 文件名格式？
  备份文件格式为 文件名.年月日时分秒（如 app.log.20231001120000）。

---

如果需要更高级的功能（如按小时切割、自定义文件名规则），可以考虑其他库（如 go-file-rotatelogs）。但对于大多数场景，Lumberjack 足够简洁高效。