logrotate

README

logrotate

Concurrency safe logging writer for Golang for application-side log rotation.

Motivation

In general, application-side log rotation should be avoided. Log rotation is best done through logrotate and other tools. However, some applications are constrained to only application-side log rotation and benefit from this package.

Usage

go get github.com/easyCZ/logrotate

package main

import (
	"fmt"
	"log"
	"os"
	"time"
    
    "github.com/easyCZ/logrotate"
)

func main() {
	logger := log.New(os.Stderr, "logrotate", log.LstdFlags) // Or any other logger conforming to golang's log.Logger
	writer, err := logrotate.New(logger, logrotate.Options{
        // Where should the writer be outputting files?
        // If the directory does not exist, it will be created.
        // Required.
		Directory:       "path/to/my/logs/directory",
        // What is the maximum size of each file?
        // Optional. Use 0 for unlimited.
		MaximumFileSize: 1024 * 1024 * 1024,
        // How often should a new file be created, based on time?
        // Optional. Use 0 to disable time based log rotation.
		MaximumLifetime: time.Hour,
        // How would you like to name your files?
        // Invoked each time a new file is being created.
        FileNameFunc:    logrotate.DefaultFilenameFunc,
	})
	if err != nil {
		// handle err
	}
    
    // ...
    
    // Ensure all messages are flushed to files before exiting 
    if err := writer.Close(); err != nil {
        // handle err
    }   
}

Usage with Golang's log.Logger

package main

import (
	"log"
	"os"

	"github.com/easyCZ/logrotate"
)

func main() {
	// Write logrotate's own log lines to stderr
	stderrLogger := log.New(os.Stderr, "logrotate", log.LstdFlags)

	writer, err := logrotate.New(stderrLogger, logrotate.Options{
		Directory: "/path/to/my/logs",
		// see other options above
	})

	// Your application logger, using logrotate as the backing Writer implementation.
	logger := log.New(writer, "application", log.LstdFlags)

    // Ensure all messages are flushed to files before exiting 
    if err := writer.Close(); err != nil {
        // handle err
    }  
}

Usage with logrus

package main

import (
	"os"
	log "github.com/sirupsen/logrus"
	logrotate "github.com/easyCZ/logrotate"
)

func init() {
	writer, err := logrotate.New(logger, logrotate.Options{
		Directory: "path/to/my/logs/directory",
	})
	if err != nil {
		// handle err
	}
	// Output to stdout instead of the default stderr
	// Can be any io.Writer, see below for File example
	log.SetOutput(writer)
}

Documentation

Overview

Package logrotate implements application-side log rotation.

logrotate supports the following modes:

• size: rotate files when they reach particular size
• time: rotate files after a period of time elapses

Index

• func DefaultFilenameFunc() string
• func RandomHash(length int) string
• type Options
• type Writer
  • func New(logger *log.Logger, opts Options) (*Writer, error)
  • func (w *Writer) Close() error
  • func (w *Writer) Write(p []byte) (n int, err error)

Functions

func DefaultFilenameFunc

func DefaultFilenameFunc() string

func RandomHash

func RandomHash(length int) string

https://stackoverflow.com/questions/22892120/how-to-generate-a-random-string-of-a-fixed-length-in-go

Types

type Options

type Options struct {
	// Directory defines the directory where log files will be written to.
	// If the directory does not exist, it will be created.
	Directory string

	// MaximumFileSize defines the maximum size of each log file in bytes.
	// When MaximumFileSize == 0, no upper bound will be enforced.
	// No file will be greater than MaximumFileSize. A Write() which would
	// exceed MaximumFileSize will instead cause a new file to be created.
	// If a Write() is attempting to write more bytes than specified by
	// MaximumFileSize, the write will be skipped.
	MaximumFileSize int64

	// MaximumLifetime defines the maximum amount of time a file will
	// be written to before a rotation occurs.
	// When MaximumLifetime == 0, no log rotation will occur.
	MaximumLifetime time.Duration

	// FileNameFunc specifies the name a new file will take.
	// FileNameFunc must ensure collisions in filenames do not occur.
	// Do not rely on timestamps to be unique, high throughput writes
	// may fall on the same timestamp.
	// Eg.
	// 	2020-03-28_15-00-945-<random-hash>.log
	// When FileNameFunc is not specified, DefaultFilenameFunc will be used.
	FileNameFunc func() string

	// FlushAfterEveryWrite specifies whether the writer should flush
	// the buffer after every write.
	FlushAfterEveryWrite bool
}

Options define configuration options for Writer

type Writer

type Writer struct {
	// contains filtered or unexported fields
}

Writer is a concurrency-safe writer with file rotation.

func New

func New(logger *log.Logger, opts Options) (*Writer, error)

New creates a new concurrency safe Writer which performs log rotation.

func (*Writer) Close

func (w *Writer) Close() error

Close closes the writer. Any accepted writes will be flushed. Any new writes will be rejected. Once Close() exits, files are synchronized to disk.

func (*Writer) Write

func (w *Writer) Write(p []byte) (n int, err error)

Write writes p into the current file, rotating if necessary. Write is non-blocking, if the writer's queue is not full. Write is blocking otherwise.