logrot

README

Logrot

Package logrot implements a log file writer with rotation and gzip compression. The rotation and compression are handled as needed during write operations.

Documentation at https://godoc.org/xi2.org/x/logrot.

Download and install with go get xi2.org/x/logrot.

Documentation

Overview

Package logrot implements a log file writer with rotation and gzip compression. The rotation and compression are handled as needed during write operations.

Note: The API is presently experimental and may change.

Example

Suppose you have a log file that looks like this:

-rw------- 1 user user  876543 Aug 24 02:41 logfile

and you open it with Open specifying a maxSize parameter of 1000000 bytes and a maxFiles parameter of 3.

w, err := logrot.Open("logfile", 0600, 1000000, 3)

If you write a further 1000000 bytes Logrot will perform a rotation during the write and you'll be left with something like this:

-rw------- 1 user user  876564 Aug 24 02:44 logfile
-rw------- 1 user user  115460 Aug 24 02:44 logfile.1.gz

Write a further 500000 bytes and you'll get this:

-rw------- 1 user user  376585 Aug 24 02:45 logfile
-rw------- 1 user user  111956 Aug 24 02:45 logfile.1.gz
-rw------- 1 user user  115460 Aug 24 02:44 logfile.2.gz

Lastly, writing a further 1000000 bytes gives:

-rw------- 1 user user  376617 Aug 24 02:45 logfile
-rw------- 1 user user  122492 Aug 24 02:45 logfile.1.gz
-rw------- 1 user user  111956 Aug 24 02:45 logfile.2.gz

There is no logfile.3.gz created since maxFiles is 3.

In the example presented here, as is typical for normal log files, logfile.1.gz and logfile.2.gz will be equal to or just under maxSize bytes when decompressed. There is one unusual case where you will end up with files greater than maxSize which is if you write more than maxSize bytes without a newline. Logrot only splits files at newlines so in this case it allows the log file to grow larger and then splits it when/if a newline is finally written.

Use with the standard library log package

To use logrot with the standard library log package, simply pass the result of Open to log.SetOutput:

w, err := logrot.Open("logfile", 0600, 1000000, 3)
if err != nil {
    panic(err)
}
log.SetOutput(w)

Index

• func Open(path string, perm os.FileMode, maxSize int64, maxFiles int) (io.WriteCloser, error)

Functions

func Open

func Open(path string, perm os.FileMode, maxSize int64, maxFiles int) (io.WriteCloser, error)

Open opens the file at path for writing in append mode. If it does not exist it is created with permissions of perm.

The returned WriteCloser keeps track of the size of the file and the position of the most recent newline. If during a call to Write a particular byte to be written would cause the file size to exceed maxSize bytes, and at least one newline has been written to the file already, then a rotation occurs before the byte is written. A rotation is the following procedure:

Let N = highest n such that <path>.<n>.gz exists or zero otherwise. Let M = maxFiles. Starting at n = N, while n > M-2 and n > 0 delete <path>.<n>.gz and decrement n. Then, while n > 0, rename <path>.<n>.gz to <path>.<n+1>.gz and decrement n. Next, if M > 1, the contents of <path> up to and including the final newline are gzipped and saved to the file <path>.1.gz . Lastly, the contents of <path> beyond the final newline are copied to the beginning of the file and <path> is truncated to contain just those contents.

It is safe to call Write/Close from multiple goroutines.