lumberjack 是一个将日志写入滚动文件的Go包。

注意，lumberjack v2.0，将使用gopkg.in导入，因此：

import "gopkg.in/natefinch/lumberjack.v2"

包名仍然是简单的lumberjack，代码位于v2.0分支下的https://github.com/natefinch/lumberjack。

lumberjack 打算成为日志基础设施的一部分。它不是一个一体化的解决方案，而是一个位于日志堆栈底部的可插入组件，它只是控制要写入日志的文件。

lumberjack 适合任何可以写入io的日志包。写入器，包括标准库的日志包。

lumberjack 假设只有一个进程正在写入输出文件。在同一台机器上的多个进程中使用相同的lumberjack配置将导致不正确的行为。

Example

要将lumberjack与标准库的日志包一起使用，只需在应用程序启动时将它传递到SetOutput函数中。
Code:

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

type Logger

type Logger struct {
     // Filename is the file to write logs to.  Backup log files will be retained
    // in the same directory.  It uses <processname>-lumberjack.log in
    // os.TempDir() if empty.
    // 文件名称是要写入日志的文件。备份的日志文件将被保留在相同目录。
    //如果为空，会在os.TempDir() 使用 <processname>-lumberjack.log
    Filename string `json:"filename" yaml:"filename"`
     // MaxSize is the maximum size in megabytes of the log file before it gets
    // rotated. It defaults to 100 megabytes.
    //MaxSize是以兆字节为单位的日志文件在被旋转之前的最大大小。默认为100兆。
    MaxSize int `json:"maxsize" yaml:"maxsize"`
    // MaxAge is the maximum number of days to retain old log files based on the
    // timestamp encoded in their filename.  Note that a day is defined as 24
    // hours and may not exactly correspond to calendar days due to daylight
    // savings, leap seconds, etc. The default is not to remove old log files
    // based on age.
    //MaxAge是根据文件名中编码的时间戳保留旧日志文件的最大天数。
    //请注意，一天被定义为24小时，由于夏令时、闰秒等原因，可能与日历日不完全对应。
    //默认情况下，不基于年龄删除旧的日志文件。
    MaxAge int `json:"maxage" yaml:"maxage"`
    // MaxBackups is the maximum number of old log files to retain.  The default
    // is to retain all old log files (though MaxAge may still cause them to get
    // deleted.)
    //MaxBackups是要保留的旧日志文件的最大数量。
    //默认情况是保留所有旧的日志文件(尽管MaxAge仍然可能导致删除它们)。
    MaxBackups int `json:"maxbackups" yaml:"maxbackups"`
    // LocalTime determines if the time used for formatting the timestamps in
    // backup files is the computer's local time.  The default is to use UTC
    // time.
    //LocalTime确定用于格式化备份文件中的时间戳的时间是否为计算机的本地时间。
    //默认是使用UTC时间。
    LocalTime bool `json:"localtime" yaml:"localtime"`
    // Compress determines if the rotated log files should be compressed
    // using gzip. The default is not to perform compression.
    //Compress决定是否应该使用gzip对旋转后的日志文件进行压缩。
    //默认是不执行压缩。
    Compress bool `json:"compress" yaml:"compress"`
    // contains filtered or unexported fields
}

Logger 是一个 io.WriteCloser,写入指定的文件名。

Logger在第一次写入时，打开或者创建日志文件。如果文件存在并且小于MaxSize兆字节，lumberjack将打开并附加到该文件。如果文件存在且其大小为>= MaxSize兆字节，则通过将当前时间放在紧邻文件扩展名(如果没有扩展名，则放在文件名的末尾)的名称中的时间戳中来重命名该文件。然后使用原始文件名创建一个新的日志文件。

每当写操作将导致当前日志文件超过MaxSize兆字节时，将关闭当前文件，重新命名，并使用原始名称创建一个新的日志文件。因此，您给Logger的文件名总是“当前”日志文件。

备份使用以名称-时间戳的形式给出给Logger的日志文件名。Ext，其中name是没有扩展名的文件名，timestamp是日志以时间格式旋转的时间。时间格式为2006-01-02T15-04-05.000，分机号为原分机号。例如，如果你的日志。文件名是/var/log/foo/server.log，在2016年11月11日下午6:30创建的备份将使用文件名/var/log/foo/server-2016-11-04T18-30-00.000.log

Cleaning Up Old Log Files

每当创建一个新的日志文件时，旧的日志文件可能会被删除。根据编码的时间戳，最新的文件将被保留，最多保留一个等于MaxBackups的数字(如果MaxBackups为0，则保留所有的文件)。任何编码时间戳比MaxAge日期早的文件都会被删除，而不管MaxBackups。注意，时间戳中编码的时间是旋转时间，它可能与上次写入该文件的时间不同。

如果MaxBackups和MaxAge都为0，则不会删除旧的日志文件。

func (*Logger) Close

func (l *Logger) Close() error

Close 实现了 io.Closer,关闭当前日志文件。

func (*Logger) Rotate

func (l *Logger) Rotate() error

Rotate引起关闭存在的日志文件，立即创建一个新的。这是一个辅助函数，适用于那些想要在常规旋转规则之外初始化旋转的应用程序，比如对SIGHUP的响应。在循环之后，将根据常规规则开始对旧日志文件的清理。

Example

如何旋转以响应SIGHUP的示例。

Code:

l := &lumberjack.Logger{}
log.SetOutput(l)
c := make(chan os.Signal, 1)
signal.Notify(c, syscall.SIGHUP)
go func() {
    for {
        <-c
        l.Rotate()
    }
}()

func (*Logger) Write

func (l *Logger) Write(p []byte) (n int, err error)

实现了io.Writer写。如果写入将导致日志文件大于MaxSize，则关闭该文件，重新命名为包含当前时间的时间戳，并使用原始日志文件名创建一个新的日志文件。如果写入的长度大于MaxSize，则返回错误。