logrotate

README

logrotate

Utilities to support logfile rotation in Go - compatible with Linux 'logrotate'.

Documentation

Overview

Package logrotate provides a clean simple way to implement log file writing with rotation of the logfiles, e.g. after a certain time or beyond a certain size. Log rotation can depend on operating system signals and will typically be used with Linux 'logrotate'.

Index

• Variables
• func MustLogWriterWithSignals(logName string, defaultWriter io.Writer) io.Writer
• func NewLogWriterWithSignals(logName string, defaultWriter io.Writer) (io.Writer, error)
• type ReopenWriter
  • func NewReopenWriter(fileName string) ReopenWriter

Examples

• MustLogWriterWithSignals

Variables

var Printf = func(format string, v ...any) {
	log.Printf(format, v...)
}

Printf emits messages via log.Printf and is used by NewLogWriterWithSignals and MustLogWriterWithSignals, reporting whenever any signal has been received. Alter this before calling those functions if different behaviour is required.

Functions

func MustLogWriterWithSignals

func MustLogWriterWithSignals(logName string, defaultWriter io.Writer) io.Writer

MustLogWriterWithSignals opens a log file for writing and attaches a signal handler (signals.RunOnPoke) to it. Therefore, when the program receives SIGHUP or SIGUSR1, it will close then reopen the log file, allowing log rotation to happen.

Note that the logName may be blank or "-", in which case the defaultWriter will be used instead of a log file; there is no signal handler in this case.

The returned writer is a ReopenWriter unless the logName is blank or "-".

See NewLogWriterWithSignals. If an error arises because the file cannot be opened, this will cause a panic.

Example

// This shows using MustLogWriterWithSignals to obtain an io.Writer
// that is used for log or log/slog logging.

defer os.Remove("example.log") // this is just to keep the example tidy

// Open the log writer and register it to handle SIGHUP & SIGUSR1.
// Note that os.Stdout isn't actually used in this example but might be
// needed if the filename is a configuration parameter that might take
// the special value "-" to indicate stdout.
lw := MustLogWriterWithSignals("example.log", os.Stdout)

// lgr is the 'basic' log package
lgr := log.New(lw, "", 0)

// we could use log/slog instead here
//lgr := slog.New(slog.NewTextHandler(lw, &slog.HandlerOptions{}))

// ... lots of interesting things happen inside the application
lgr.Print("Hello world")

// Unix Logrotate can rename the file then send SIGHUP to the application.
// If the application receives SIGHUP or SIGUSR1, "example.log" will be
// closed then re-opened. So the old version is closed and kept and the
// application carries on writing to "example.log", but it's now a new file,

lgr.Print("Something interesting happened")
// ... lots more interesting things happen inside the application

// That's the end of the example. Now let's check that the log
// file exists, with the correct messages in it.
file, _ := os.Open("example.log")
content, _ := io.ReadAll(file)
fmt.Println(string(content))

Output:

Hello world
Something interesting happened

func NewLogWriterWithSignals

func NewLogWriterWithSignals(logName string, defaultWriter io.Writer) (io.Writer, error)

NewLogWriterWithSignals opens a log file for writing and attaches a signal handler (signals.RunOnPoke) to it. Therefore, when the program receives SIGHUP or SIGUSR1, it will close then reopen the log file, allowing log rotation to happen.

Note that the logName may be blank or "-", in which case the defaultWriter will be used instead of a log file; there is no signal handler in this case.

The returned writer is a ReopenWriter unless the logName is blank or "-".

Types

type ReopenWriter

type ReopenWriter interface {
	io.WriteCloser
	io.StringWriter
	FileName() string
	Open() error
}

ReopenWriter is a WriteCloser that is able to close and reopen cleanly whilst in use. It is intended for writing log files, so always appends to existing files instead of truncating them.

This will work well with the 'logrotate' utility on Linux. On rotation, 'logrotate' should rename the old file and then signal to the application, usually via SIGHUP or SIGUSR1.

func NewReopenWriter

func NewReopenWriter(fileName string) ReopenWriter

NewReopenWriter returns a new ReopenWriter with a given filename. The filename stays constant even when the file is closed and reopened.

This function does not register any signal handling. For writing logfiles with Unix logrotate, see NewLogWriterWithSignals.