lumberjack.v2

Lumberjack is a Go package for writing logs to rolling files. It is designed as a pluggable component that implements io.WriteCloser, making it compatible with any logging package that accepts an io.Writer (such as the standard library's log package).

Important: This is v2.0 and must be imported using gopkg.in:

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

Warning: Lumberjack assumes that only one process is writing to the output files. Using the same configuration from multiple processes on the same machine will result in improper behavior.

The Logger struct defines how log files are rotated and retained. It implements io.WriteCloser and opens or creates the logfile on the first Write call.

Fields:

• Filename: The file to write logs to. If empty, it uses <processname>-lumberjack.log in os.TempDir().
• MaxSize: Maximum size in megabytes before rotation (default: 100).
• MaxAge: Maximum number of days to retain old log files (default: 0, meaning no files are removed by age).
• MaxBackups: Maximum number of old log files to retain (default: 0, meaning all old files are retained).
• LocalTime: If true, uses local time for backup file timestamps (default: false/UTC).
• Compress: If true, rotated files are compressed using gzip (default: false).

Lumberjack v2 should be imported using the gopkg.in path to ensure correct versioning:

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

To use lumberjack with the standard library's log package, pass a pointer to a lumberjack.Logger into log.SetOutput during application startup.

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

The Rotate() method causes the Logger to close the existing log file and immediately create a new one. This is useful for initiating rotations in response to external signals like SIGHUP.

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

go func() {
    for {
        <-c
        l.Rotate()
    }
}()

The Logger type provides the following methods to satisfy io.Writer, io.Closer, and manual rotation requirements.

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

Single Process Requirement

Lumberjack assumes that only one process is writing to the output files. Using the same Logger configuration from multiple processes on the same machine will result in improper behavior.

Rotation Naming Convention

Backups are named using the format name-timestamp.ext, where the timestamp follows 2006-01-02T15-04-05.000. For example, /var/log/foo/server.log becomes /var/log/foo/server-2016-11-04T18-30-00.000.log after rotation.