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 ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Open ¶
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.
Types ¶
This section is empty.