README
¶
logrotate
A powerful log rotation package for Go.
Examples
Use with stdlib log
See demo: Use with stdlib log
func main() {
// logrotate is safe for concurrent use.
l, _ := logrotate.New("/path/to/log.%Y%m%d")
log.SetOutput(l)
log.Printf("Hello, World!")
}
Use with Zap
See demo: Use with Zap
func main() {
l, _ := logrotate.New(
"/path/to/log.%Y%m%d%H",
logrotate.WithSymlink("/path/to/log"), // symlink to current logfile
logrotate.WithMaxAge(30*24*time.Hour), // remove logs older than 30 days
logrotate.WithMaxInterval(time.Hour), // rotate every hour
)
w := zapcore.AddSync(l)
core := zapcore.NewCore(
zapcore.NewJSONEncoder(zap.NewProductionEncoderConfig()),
w,
zap.InfoLevel,
)
logger := zap.New(core)
logger.Info("Hello, World!")
}
Options
Pattern (Required)
The pattern used to generate actual log file names. You should use the strftime (3) - format date and time format. For example:
// YYYY-mm-dd (e.g.: 2024-04-04)
logrotate.New("/path/to/log.%Y-%m-%d")
// YY-mm-dd HH:MM:SS (e.g.: 2024-04-04 10:01:49)
logrotate.New("/path/to/log.%Y-%m-%d %H:%M:%S")
Clock (default: logrotate.DefaultClock)
You may specify an object that implements the logrotate.Clock interface.
When this option is supplied, it's used to determine the current time to
base all of the calculations on. For example, if you want to base your
calculations in UTC, you may create a UTC clock:
type UTCClock struct{}
func (UTCClock) Now() time.Time {
return time.Now().UTC()
}
logrotate.New(
"/path/to/log.%Y%m%d",
logrotate.WithClock(UTCClock),
)
Symlink (default: "")
You can set a symlink for the current log file being used. This allows you to always check at the same location for current log file even if the logs were rotated.
logrotate.New(
"/path/to/log.%Y%m%d",
logrotate.WithSymlink("/path/to/current"),
)
# Check current log file
$ tail -f /path/to/current
The symlink that share the same parent directory with the main log path will get a special treatment: linked paths will be RELATIVE to the main log file.
| Main log file pattern | Symlink path | Linked path |
|---|---|---|
| /path/to/log.%Y%m%d | /path/to/log | log.YYYYMMDD |
| /path/to/log.%Y%m%d | /path/to/nested/log | ../log.YYYYMMDD |
| /path/to/log.%Y%m%d | /foo/bar/baz/log | /path/to/log.YYYYMMDD |
If not provided, no link will be written.
MaxInterval (default: 24 hours)
Interval between file rotation. By default logs are rotated every 24 hours.
In particular, the minimal interval unit is in time.Second level.
Note: Remember to use time.Duration values.
// Rotate every hour
logrotate.New(
"/path/to/log.%Y%m%d",
logrotate.WithMaxInterval(time.Hour),
)
MaxSequence (default: 0)
MaxSequence controls the max count of rotated log files in the same interval. If over max sequence limit, the logger will clear content of the log file with max sequence suffix, and then write to it.
If MaxSequence <= 0, that means no limit of rotated log files in the same interval.
// limit max 100 rotated files in the same interval
logrotate.New(
"/path/to/log.%Y%m%d",
logrotate.MaxSequence(100),
)
MaxSize (default: 100 MiB)
MaxSize is the maximum size in MiB (megabytes) of the log file before it gets rotated. It defaults to 100 MiB.
// Rotate every 10 MiB
logrotate.New(
"/path/to/log.%Y%m%d",
logrotate.WithMaxSize(10*1024*1024),
)
MaxAge (default: 0)
Retain old log files based on the timestamp encoded in their filename. If MaxAge <= 0, that means not remove old log files based on age.
Note: Remember to use time.Duration values.
// Remove logs older than 7 days
logrotate.New(
"/path/to/log.%Y%m%d",
logrotate.WithMaxAge(7*24*time.Hour),
)
MaxBackups (default: 0)
The maximum number of old log files to retain. If MaxBackups <= 0, that means retain all old log files (though MaxAge may still cause them to be removed.)
// Remove logs except latest 7 files
logrotate.New(
"/path/to/log.%Y%m%d",
logrotate.WithMaxBackups(7),
)
WriteChan (default: 0)
WithWriteChan sets the buffered write channel size.
If write chan size <= 0, it will write to the current file directly.
If write chan size > 0, the logger just writes to write chan and return, and it's the write loop goroutine's responsibility to sink the write channel to files asynchronously in background. So there is no blocking disk I/O operations, and write would not block even if write channel is full as it will auto discard log lines.
// Use buffered write and set channel size to 100
logrotate.New(
"/path/to/log.%Y%m%d",
logrotate.WithWriteChan(100),
)
Documentation
¶
Overview ¶
Package logrotate can automatically rotate log files when you write to them according to the specified filename pattern and options.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var DefaultClock = systemClock{}
DefaultClock is the default clock used by logrotate in operations that require time. This clock uses the system clock for all operations.
Functions ¶
This section is empty.
Types ¶
type Logger ¶
type Logger struct {
// contains filtered or unexported fields
}
Logger is an io.WriteCloser that writes to the appropriate filename. It can get automatically rotated as you write to it.
func New ¶
New creates a new concurrent safe Logger object with the provided filename pattern and options.
Example ¶
dir := "_logs/example/"
defer os.RemoveAll(dir)
l, _ := New(
dir+"test.log",
WithMaxSize(10), // 10 bytes
)
log.SetOutput(l)
log.Printf("Hello, World!") // 13 bytes
log.Printf("Hello, World!") // 13 bytes
time.Sleep(time.Second) // ensure already sink to files
l.Close()
files, _ := os.ReadDir(dir)
for _, file := range files {
fmt.Println(file.Name())
}
Output: test.log test.log.1
func (*Logger) Close ¶
Close implements io.Closer. It closes the writeLoop and millLoop goroutines and the current log file.
func (*Logger) Rotate ¶
Rotate forcefully rotates the log files. It will close the existing log file and immediately create a new one. This is a helper function for applications that want to initiate rotations outside of the normal rotation rules, such as in response to SIGHUP. After rotating, this initiates removal of old log files according to the configuration.
If the new generated log file name clash because file already exists, a sequence suffix of the form ".1", ".2", ".3" and so forth are appended to the end of the log file.
func (*Logger) Write ¶
Write implements io.Writer. If writeChSize <= 0, then it writes to the current file directly. Otherwise, it just writes to writeCh, so there is no blocking disk I/O operations and would not block unless writeCh is full. In the meantime, the writeLoop goroutine will sink the writeCh to files asynchronously in background.
Write writes len(b) bytes from b to the File. It returns the number of bytes written and an error, if any. Write returns a non-nil error when n != len(b).
NOTE: It's an undefined behavior if you still call Write after Close called. Maybe it would sink to files, maybe not, but it won't panic.
type Option ¶
type Option func(*Options)
Option is the functional option type.
func WithClock ¶
WithClock specifies the clock used by Logger to determine the current time. It defaults to the system clock with time.Now.
func WithMaxAge ¶
WithMaxAge sets the max age to retain old log files based on the timestamp encoded in their filename. If MaxAge <= 0, that means not remove old log files based on age.
Default: 0
func WithMaxBackups ¶
WithMaxBackups sets the maximum number of old log files to retain. If MaxBackups <= 0, that means retain all old log files (though MaxAge may still cause them to be removed.)
Default: 0
func WithMaxInterval ¶
WithMaxInterval sets the maximum interval between file rotation. In particular, the minimal interval unit is in time.Second level.
Default: 24 hours
func WithMaxSequence ¶
WithMaxSequence controls the max count of rotated log files in the same interval. If over max sequence limit, the logger will clear content of the log file with max sequence suffix, and then write to it.
If MaxSequence <= 0, that means no limit of rotated log files in the same interval.
Default: 0
func WithMaxSize ¶
WithMaxSize sets the maximum size of log file before it gets rotated. If MaxSize <= 0, that means not rotate log file based on size.
Default: 100 MiB
func WithSymlink ¶
WithSymlink sets the symbolic link name that gets linked to the current filename being used.
Default: ""
func WithWriteChan ¶
WithWriteChan sets the buffered write channel size.
If write chan size <= 0, it will write to the current file directly.
If write chan size > 0, the logger just writes to write chan and return, and it's the write loop goroutine's responsibility to sink the write channel to files asynchronously in background. So there is no blocking disk I/O operations, and write would not block even if write channel is full as it will auto discard log lines.
Default: 0
Source Files
Directories