|
| 1 | +# lumberjack [](https://godoc.org/gopkg.in/natefinch/lumberjack.v2) [](https://travis-ci.org/natefinch/lumberjack) [](https://ci.appveyor.com/project/natefinch/lumberjack) [](https://coveralls.io/r/natefinch/lumberjack?branch=v2.0) |
| 2 | + |
| 3 | +### Lumberjack is a Go package for writing logs to rolling files. |
| 4 | + |
| 5 | +Package lumberjack provides a rolling logger. |
| 6 | + |
| 7 | +Note that this is v2.0 of lumberjack, and should be imported using gopkg.in |
| 8 | +thusly: |
| 9 | + |
| 10 | + import "gopkg.in/natefinch/lumberjack.v2" |
| 11 | + |
| 12 | +The package name remains simply lumberjack, and the code resides at |
| 13 | +https://github.com/natefinch/lumberjack under the v2.0 branch. |
| 14 | + |
| 15 | +Lumberjack is intended to be one part of a logging infrastructure. |
| 16 | +It is not an all-in-one solution, but instead is a pluggable |
| 17 | +component at the bottom of the logging stack that simply controls the files |
| 18 | +to which logs are written. |
| 19 | + |
| 20 | +Lumberjack plays well with any logging package that can write to an |
| 21 | +io.Writer, including the standard library's log package. |
| 22 | + |
| 23 | +Lumberjack assumes that only one process is writing to the output files. |
| 24 | +Using the same lumberjack configuration from multiple processes on the same |
| 25 | +machine will result in improper behavior. |
| 26 | + |
| 27 | + |
| 28 | +**Example** |
| 29 | + |
| 30 | +To use lumberjack with the standard library's log package, just pass it into the SetOutput function when your application starts. |
| 31 | + |
| 32 | +Code: |
| 33 | + |
| 34 | +```go |
| 35 | +log.SetOutput(&lumberjack.Logger{ |
| 36 | + Filename: "/var/log/myapp/foo.log", |
| 37 | + MaxSize: 500, // megabytes |
| 38 | + MaxBackups: 3, |
| 39 | + MaxAge: 28, //days |
| 40 | + Compress: true, // disabled by default |
| 41 | +}) |
| 42 | +``` |
| 43 | + |
| 44 | + |
| 45 | + |
| 46 | +## type Logger |
| 47 | +``` go |
| 48 | +type Logger struct { |
| 49 | + // Filename is the file to write logs to. Backup log files will be retained |
| 50 | + // in the same directory. It uses <processname>-lumberjack.log in |
| 51 | + // os.TempDir() if empty. |
| 52 | + Filename string `json:"filename" yaml:"filename"` |
| 53 | + |
| 54 | + // MaxSize is the maximum size in megabytes of the log file before it gets |
| 55 | + // rotated. It defaults to 100 megabytes. |
| 56 | + MaxSize int `json:"maxsize" yaml:"maxsize"` |
| 57 | + |
| 58 | + // MaxAge is the maximum number of days to retain old log files based on the |
| 59 | + // timestamp encoded in their filename. Note that a day is defined as 24 |
| 60 | + // hours and may not exactly correspond to calendar days due to daylight |
| 61 | + // savings, leap seconds, etc. The default is not to remove old log files |
| 62 | + // based on age. |
| 63 | + MaxAge int `json:"maxage" yaml:"maxage"` |
| 64 | + |
| 65 | + // MaxBackups is the maximum number of old log files to retain. The default |
| 66 | + // is to retain all old log files (though MaxAge may still cause them to get |
| 67 | + // deleted.) |
| 68 | + MaxBackups int `json:"maxbackups" yaml:"maxbackups"` |
| 69 | + |
| 70 | + // LocalTime determines if the time used for formatting the timestamps in |
| 71 | + // backup files is the computer's local time. The default is to use UTC |
| 72 | + // time. |
| 73 | + LocalTime bool `json:"localtime" yaml:"localtime"` |
| 74 | + |
| 75 | + // Compress determines if the rotated log files should be compressed |
| 76 | + // using gzip. The default is not to perform compression. |
| 77 | + Compress bool `json:"compress" yaml:"compress"` |
| 78 | + // contains filtered or unexported fields |
| 79 | +} |
| 80 | +``` |
| 81 | +Logger is an io.WriteCloser that writes to the specified filename. |
| 82 | + |
| 83 | +Logger opens or creates the logfile on first Write. If the file exists and |
| 84 | +is less than MaxSize megabytes, lumberjack will open and append to that file. |
| 85 | +If the file exists and its size is >= MaxSize megabytes, the file is renamed |
| 86 | +by putting the current time in a timestamp in the name immediately before the |
| 87 | +file's extension (or the end of the filename if there's no extension). A new |
| 88 | +log file is then created using original filename. |
| 89 | + |
| 90 | +Whenever a write would cause the current log file exceed MaxSize megabytes, |
| 91 | +the current file is closed, renamed, and a new log file created with the |
| 92 | +original name. Thus, the filename you give Logger is always the "current" log |
| 93 | +file. |
| 94 | + |
| 95 | +Backups use the log file name given to Logger, in the form `name-timestamp.ext` |
| 96 | +where name is the filename without the extension, timestamp is the time at which |
| 97 | +the log was rotated formatted with the time.Time format of |
| 98 | +`2006-01-02T15-04-05.000` and the extension is the original extension. For |
| 99 | +example, if your Logger.Filename is `/var/log/foo/server.log`, a backup created |
| 100 | +at 6:30pm on Nov 11 2016 would use the filename |
| 101 | +`/var/log/foo/server-2016-11-04T18-30-00.000.log` |
| 102 | + |
| 103 | +### Cleaning Up Old Log Files |
| 104 | +Whenever a new logfile gets created, old log files may be deleted. The most |
| 105 | +recent files according to the encoded timestamp will be retained, up to a |
| 106 | +number equal to MaxBackups (or all of them if MaxBackups is 0). Any files |
| 107 | +with an encoded timestamp older than MaxAge days are deleted, regardless of |
| 108 | +MaxBackups. Note that the time encoded in the timestamp is the rotation |
| 109 | +time, which may differ from the last time that file was written to. |
| 110 | + |
| 111 | +If MaxBackups and MaxAge are both 0, no old log files will be deleted. |
| 112 | + |
| 113 | + |
| 114 | + |
| 115 | + |
| 116 | + |
| 117 | + |
| 118 | + |
| 119 | + |
| 120 | + |
| 121 | + |
| 122 | + |
| 123 | +### func (\*Logger) Close |
| 124 | +``` go |
| 125 | +func (l *Logger) Close() error |
| 126 | +``` |
| 127 | +Close implements io.Closer, and closes the current logfile. |
| 128 | + |
| 129 | + |
| 130 | + |
| 131 | +### func (\*Logger) Rotate |
| 132 | +``` go |
| 133 | +func (l *Logger) Rotate() error |
| 134 | +``` |
| 135 | +Rotate causes Logger to close the existing log file and immediately create a |
| 136 | +new one. This is a helper function for applications that want to initiate |
| 137 | +rotations outside of the normal rotation rules, such as in response to |
| 138 | +SIGHUP. After rotating, this initiates a cleanup of old log files according |
| 139 | +to the normal rules. |
| 140 | + |
| 141 | +**Example** |
| 142 | + |
| 143 | +Example of how to rotate in response to SIGHUP. |
| 144 | + |
| 145 | +Code: |
| 146 | + |
| 147 | +```go |
| 148 | +l := &lumberjack.Logger{} |
| 149 | +log.SetOutput(l) |
| 150 | +c := make(chan os.Signal, 1) |
| 151 | +signal.Notify(c, syscall.SIGHUP) |
| 152 | + |
| 153 | +go func() { |
| 154 | + for { |
| 155 | + <-c |
| 156 | + l.Rotate() |
| 157 | + } |
| 158 | +}() |
| 159 | +``` |
| 160 | + |
| 161 | +### func (\*Logger) Write |
| 162 | +``` go |
| 163 | +func (l *Logger) Write(p []byte) (n int, err error) |
| 164 | +``` |
| 165 | +Write implements io.Writer. If a write would cause the log file to be larger |
| 166 | +than MaxSize, the file is closed, renamed to include a timestamp of the |
| 167 | +current time, and a new log file is created using the original log file name. |
| 168 | +If the length of the write is greater than MaxSize, an error is returned. |
| 169 | + |
| 170 | + |
| 171 | + |
| 172 | + |
| 173 | + |
| 174 | + |
| 175 | + |
| 176 | + |
| 177 | + |
| 178 | +- - - |
| 179 | +Generated by [godoc2md](http://godoc.org/github.com/davecheney/godoc2md) |
0 commit comments