---

简介

lumberjack是一个日志滚动记录器。写入lumberjack的日志达到一定的条件后会进行存档（普通文件的形式，或压缩文件的形式），然后新建另一个同名文件（原文件存档时会重命名）继续记录。但是lumberjack本身并不包含日志的基础功能，例如日志等级、日志格式化等。理论上可以向lumberjack写入任意文本，并实现滚动记录。一般情况下，lumberjack配合其他日志库，实现日志的滚动(rolling)记录。

简单使用

将lumberjack和go语言自带的log结合起来使用，可以这么设置：

log.SetOutput(&lumberjack.Logger{
    Filename:   "/var/log/myapp/foo.log",
    MaxSize:    500, // megabytes
    MaxBackups: 3,
    MaxAge:     28, //days
    Compress:   true, // disabled by default
})

go语言的log模块就会将日志打印到lumberjack中，lumberjack会将收到的日志写入文件，并实现滚动记录。

查看log.SetOutput接口

由此得知，lumberjack必须实现io.Writer接口才能与其他日志模块相结合。事实上，lumberjack也确实实现了io.Writer接口，同时也实现了io.Closer 接口。

1. Logger 结构体

lumberjack对外暴露的方法由Logger结构提供。先来看一下Logger的内部字段:

type Logger struct {
	// 日志文件名，归档日志也会保存在对应目录下
        // 若该值为空，则日志会保存到os.TempDir()目录下，日志文件名为
        // <processname>-lumberjack.log
	Filename string `json:"filename" yaml:"filename"`

	// 日志大小到达MaxSize(MB)就开始backup，默认值是100.
	MaxSize int `json:"maxsize" yaml:"maxsize"`

	// 旧日志保存的最大天数，默认保存所有旧日志文件
	MaxAge int `json:"maxage" yaml:"maxage"`

	// 旧日志保存的最大数量，默认保存所有旧日志文件
	MaxBackups int `json:"maxbackups" yaml:"maxbackups"`

	// backup的日志是否使用本地时间戳，默认使用UTC时间
	LocalTime bool `json:"localtime" yaml:"localtime"`

	// 对backup的日志是否进行压缩，默认不压缩
	Compress bool `json:"compress" yaml:"compress"`

	size int64  // 对于当前正在写入的文件，已经写了多少字节  
	file *os.File  // 当前正在写入的文件句柄
	mu   sync.Mutex

	millCh    chan bool
	startMill sync.Once
}

从上面的字面量注释可以看到，lumberjack.Logger支持json格式和yaml格式的配置文件，可以配置如下参数：

• Filename——日志文件名
• MaxSize——单个日志文件大小(MB)
• MaxAge——日志存活时长(天)
• MaxBackups——旧日志文件的数量
• LocalTime——是否使用本地时间，否则使用UTC时间
• Compress——是否对旧日志文件进行压缩

这几个配置参数的功能如上面的注释缩写，一目了然，无须过多解释。Logger结构实现了以下对外方法：

• Write(p []byte) (n int, err error) // 日志写入，可能会触发的日志归档，删除过期文件，压缩归档文件等
• Close() error // 关闭当前日志文件
• Rotate() error // 主动归档日志文件，而非被动触发

可以将Logger看成是io.WriterCloser 的具体实现，并且还多了一个Rotate()的主动滚动日志的方法。

2. backup日志文件的文件名

函数backupName 将原文件名转换为backup文件名，本质上的操作是在原来的文件名上附加固定格式的时间戳。若对backup文件进行压缩，无非是在此基础上增加了.gz 后缀。

在向文件名添加时间时，根据local变量可以指定使用本地时间还是UTC时间。但是lumberjack没有开放时间格式化的接口，时间格式由一个固定的包变量决定。

由于使用的是go内置的time模块完成格式化，所以这个时间格式……只能2006-xx…，据说这是go语言诞生的时间。想要更改backup的文件名，可以下载源码修改并使用。对于backup的文件名，可以举例：

原文件名：/abc/def.log
backup文件名：/abc/def-2021-01-02T19-01-31.000.log

3. 获取文件句柄

在日志系统刚启动的时候，需要获取日志文件的句柄，该句柄可能是已存在的文件的，也可能是新建的文件的句柄。openExistingOrNew 方法主要用来获取日志文件句柄：

4. 日志文件backup

当即将写入的字节数超过当前文件的剩余配额时，即 （当前文件已写入的字节）+（当前待写入字节）>= MaxSize 时，就出发了日志滚动(rolling).

日志滚动分为三步：

• 关闭原日志文件
• 重命名原日志文件，附上时间字符串
• 向通道millCh发送一个信号，以此触发后处理（例如压缩backup文件，删除过期文件等）

5. 日志滚动后处理

上面提到日志滚动会发送信号，这时候出发了后处理操作。后处理操作在另一个goroutine中进行，不会影响当前的日志写入。

6. 收集旧日志文件

在日志存放的文件夹下，-.log和-.log.gz文件都会被当成旧的日志文件。

注意oldLogFiles()方法的最后，对旧日志的文件名列表按时间排序，这一步很关键。

7. 后处理

收集完旧的日志文件后，根据MaxBackups, MaxAge, Compress三个参数完成后处理。根据MaxBackups, MaxAge 删除过期文件，根据Compress参数决定是否压缩哪些未压缩的旧日志文件。

小结

Lumberjack是一个滚动记录器，实现了io.WriteCloser 接口，本身并不具备日志功能（如格式化，日志等级等功能），只是一个文件记录器，但是经常被用来作为日志滚动记录的工具。Lumberjack滚动记录日志，日志文件在满足一定条件后就会backup，旧日志文件的文件名是在原日志文件名的基础上附加时间信息，并可以自主选择是否压缩。