rotatelogs

package module
Version: v0.0.0-...-d3151e2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 23, 2018 License: MIT Imports: 10 Imported by: 0

README

go-file-rotatelogs

Build Status

GoDoc

Port of File::RotateLogs from Perl to Go.

WARNING

This repository has been moved to github.com/lestrrat-go/file-rotatelogs. This repository exists so that libraries pointing to this URL will keep functioning, but this repository will NOT be updated in the future. Please use the new import path.

SYNOPSIS

import (
  "log"
  "net/http"

  apachelog "github.com/lestrrat/go-apache-logformat"
  rotatelogs "github.com/lestrrat/go-file-rotatelogs"
)

func main() {
  mux := http.NewServeMux()
  mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) { ... })

  logf, err := rotatelogs.New(
    "/path/to/access_log.%Y%m%d%H%M",
    rotatelogs.WithLinkName("/path/to/access_log"),
    rotatelogs.WithMaxAge(24 * time.Hour),
    rotatelogs.WithRotationTime(time.Hour),
  )
  if err != nil {
    log.Printf("failed to create rotatelogs: %s", err)
    return
  }

  http.ListenAndServe(":8080", apachelog.Wrap(mux, logf))
}

DESCRIPTION

When you integrate this to to you app, it automatically write to logs that are rotated from within the app: No more disk-full alerts because you forgot to setup logrotate!

To install, simply issue a go get:

go get github.com/lestrrat/go-file-rotatelogs

It's normally expected that this library is used with some other logging service, such as the built-in log library, or loggers such as github.com/lestrrat/go-apache-logformat.

import(
  "log"
  "github.com/lestrrat/go-file-rotatelogs"
)
  
func main() {
  rl, _ := rotatelogs.New("/path/to/access_log.%Y%m%d%H%M")

  log.SetOutput(rl)

  /* elsewhere ... */
  log.Printf("Hello, World!")
}

OPTIONS

Pattern (Required)

The pattern used to generate actual log file names. You should use patterns using the strftime (3) format. For example:

  rotatelogs.New("/var/log/myapp/log.%Y%m%d")

Clock (default: rotatelogs.Local)

You may specify an object that implements the roatatelogs.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 specify rotatelogs.UTC

  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithClock(rotatelogs.UTC),
  )

Location

This is an alternative to the WithClock option. Instead of providing an explicit clock, you can provide a location for you times. We will create a Clock object that produces times in your specified location, and configure the rotatelog to respect it.

LinkName (default: "")

Path where a symlink for the actual log file is placed. This allows you to always check at the same location for log files even if the logs were rotated

  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithLinkName("/var/log/myapp/current"),
  )
  // Else where
  $ tail -f /var/log/myapp/current

If not provided, no link will be written.

RotationTime (default: 86400 sec)

Interval between file rotation. By default logs are rotated every 86400 seconds. Note: Remember to use time.Duration values.

  // Rotate every hour
  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithRotationTime(time.Hour),
  )

MaxAge (default: 7 days)

Time to wait until old logs are purged. By default no logs are purged, which certainly isn't what you want. Note: Remember to use time.Duration values.

  // Purge logs older than 1 hour
  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithMaxAge(time.Hour),
  )

RotationCount (default: -1)

The number of files should be kept. By default, this option is disabled.

Note: MaxAge should be disabled by specifing WithMaxAge(-1) explicitly.

  // Purge logs except latest 7 files
  rotatelogs.New(
    "/var/log/myapp/log.%Y%m%d",
    rotatelogs.WithMaxAge(-1),
    rotatelogs.WithRotationCount(7),
  )

Documentation

Overview

package rotatelogs is a port of File-RotateLogs from Perl (https://metacpan.org/release/File-RotateLogs), and it allows you to automatically rotate output files when you write to them according to the filename pattern that you can specify.

Index

Constants

This section is empty.

Variables

View Source
var Local = clockFn(time.Now)

Local is an object satisfying the Clock interface, which returns the current time in the local timezone

View Source
var UTC = clockFn(func() time.Time { return time.Now().UTC() })

UTC is an object satisfying the Clock interface, which returns the current time in UTC

Functions

This section is empty.

Types

type Clock

type Clock interface {
	Now() time.Time
}

Clock is the interface used by the RotateLogs object to determine the current time

type Option

type Option interface {
	Configure(*RotateLogs) error
}

Option is used to pass optional arguments to the RotateLogs constructor

func WithClock

func WithClock(c Clock) Option

WithClock creates a new Option that sets a clock that the RotateLogs object will use to determine the current time.

By default rotatelogs.Local, which returns the current time in the local time zone, is used. If you would rather use UTC, use rotatelogs.UTC as the argument to this option, and pass it to the constructor.

func WithLinkName

func WithLinkName(s string) Option

WithLinkName creates a new Option that sets the symbolic link name that gets linked to the current file name being used.

func WithLocation

func WithLocation(loc *time.Location) Option

WithLocation creates a new Option that sets up a "Clock" interface that the RotateLogs object will use to determine the current time.

This optin works by always returning the in the given location.

func WithMaxAge

func WithMaxAge(d time.Duration) Option

WithMaxAge creates a new Option that sets the max age of a log file before it gets purged from the file system.

func WithRotationCount

func WithRotationCount(n int) Option

WithRotationCount creates a new Option that sets the number of files should be kept before it gets purged from the file system.

func WithRotationTime

func WithRotationTime(d time.Duration) Option

WithRotationTime creates a new Option that sets the time between rotation.

type OptionFn

type OptionFn func(*RotateLogs) error

OptionFn is a type of Option that is represented by a single function that gets called for Configure()

func (OptionFn) Configure

func (o OptionFn) Configure(rl *RotateLogs) error

type RotateLogs

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

RotateLogs represents a log file that gets automatically rotated as you write to it.

func New

func New(pattern string, options ...Option) (*RotateLogs, error)

New creates a new RotateLogs object. A log filename pattern must be passed. Optional `Option` parameters may be passed

func (*RotateLogs) Close

func (rl *RotateLogs) Close() error

Close satisfies the io.Closer interface. You must call this method if you performed any writes to the object.

func (*RotateLogs) CurrentFileName

func (rl *RotateLogs) CurrentFileName() string

CurrentFileName returns the current file name that the RotateLogs object is writing to

func (*RotateLogs) Write

func (rl *RotateLogs) Write(p []byte) (n int, err error)

Write satisfies the io.Writer interface. It writes to the appropriate file handle that is currently being used. If we have reached rotation time, the target file gets automatically rotated, and also purged if necessary.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL