golw

README

golw

Go Log Writer

Provide io.WriteCloser for logs to be written to.

Example

package main // import "github.com/karrick/golw/examples/simple"

import (
	"fmt"
	"os"
	"path/filepath"

	"github.com/karrick/golw"
)

func main() {
	lw, err := golw.NewLogWriter(golw.Config{
		BufferBytes: 32,
		MaxBytes:    16,
	})
	if err != nil {
		bail(err)
	}

	for i := 0; i < 128; i++ {
		n, err := lw.Write([]byte{'.'})
		if err != nil {
			bail(err)
		}
		if n != 1 {
			bail(fmt.Errorf("GOT: %v; WANT: 1", n))
		}
	}

	if err = lw.Close(); err != nil {
		bail(err)
	}
}

func bail(err error) {
	fmt.Fprintf(os.Stderr, "%s: %s\n", filepath.Base(os.Args[0]), err)
	os.Exit(1)
}

Documentation

Index

• Constants
• func Megabytes(megabytes int) int64
• type Config
• type LogWriter
  • func NewLogWriter(cfg *Config) (*LogWriter, error)
  • func (lw *LogWriter) Close() error
  • func (lw *LogWriter) Write(p []byte) (written int, err error)

Constants

const (
	// DateTime is a time format string that represents current time
	// similar to time.RFC3339Nano, but with colons changed to
	// hyphens, and only three digits of precision for fractional
	// seconds. This is convenience constant for setting TimeFormat
	// to.
	DateTime = "2006-01-02T15-04-05.000Z0700"
)

Functions

func Megabytes

func Megabytes(megabytes int) int64

Megabytes returns the number of bytes in the specified amount of megabytes.

Types

type Config

type Config struct {
	// BaseNamePrefix is an optional prefix of the base name to use
	// when creating new output files inside the directory specified
	// by Directory. When this value is the empty string, the
	// LogWriter will use base name of os.Args[0].
	BaseNamePrefix string

	// BufferSizeMax is an optional size of a buffer to use between
	// writes. When this value is -1, the LogWriter will not buffer
	// writes, but will ensure log files are rotated when their size
	// would exceed MaxBytes. When this value is zero, the LogWriter
	// will use a buffer with a default size of 128 bytes. When this
	// value is greater than zero, the LogWriter will use a byte
	// buffer of this size to reduce the number of writes to the file
	// system.
	//
	// small value <-------------------------------------> large value
	// (more interactive)                           (less interactive)
	// (less efficient)                               (more efficient)
	BufferSizeMax int

	// Directory is an optional directory for creating new files. When
	// this value is the empty string, the LogWriter will use the
	// current working directory at the time the LogWriter was
	// created.
	Directory string

	// FileMode is an optional OS file mode to use when creating new
	// files. When this value is zero, the LogWriter will default to
	// 0644, which on UNIX, is equivalent to rw-r--r--.
	FileMode fs.FileMode

	// MaxBytes is an optional maximum number of bytes to write to any
	// particular log file. When a particular Write call sends a byte
	// slice longer than this value, the LogWriter will create a new
	// file to hold the contents of the entire byte slice, regardless
	// of its size, then will create a new output file the next time
	// its Write method is invoked.
	MaxBytes int64

	// TimeFormatter is an optional function that will format a given
	// time.Time value to a string in the desired time format for the
	// purpose of creating filenames with a timestamp. When this value
	// is the empty string, the value of TimeFormat is checked, and if
	// itself not empty, used to format the time.
	TimeFormatter func(time.Time) string

	// TimeFormat is an optional format to pass to time.Time's Format
	// method to format the current time when TimeFormatter is
	// empty. This value is ignored when TimeFormatter is not
	// nil. When TimeFormatter is nil and TimeFormat is the empty
	// string, the LogWriter uses UnixNano to format the time string
	// used to name rotated log files.
	TimeFormat string
}

Config provides fields to customize behavior of a LogWriter.

type LogWriter

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

LogWriter is a io.WriteCloser that can act as the recipient of many logging libraries, and is designed to rotate log files at a specified size, and optionally buffer writes to reduce file system calls.

NOTE: When LogWriter opens a previously created log file, it does not inspect its contents to determine the time of its first write. Therefore, later if it needs to rotate logs, it will rename the pre-existing log file with a timestamp of the first write applied to the log file after it was opened using this library.

func NewLogWriter

func NewLogWriter(cfg *Config) (*LogWriter, error)

NewLogWriter returns a new LogWriter, or an error when the provided Config specifies disallowed argument values.

func (*LogWriter) Close

func (lw *LogWriter) Close() error

Close satisfies the io.Closer interface, and will flush and close the currently open log file, potentially returning an error resulting from flushing the buffer or closing the file. If the LogWriter was waiting to flush a line which was not newline terminated, it will be flushed as well, along with an appended newline character. This is done to prevent the next use of the log file from appending its first line to the middle of the previously written unterminated line.

func (*LogWriter) Write

func (lw *LogWriter) Write(p []byte) (written int, err error)

Write satisfies the io.Writer interface, allowing a program to write byte slices to the LogWriter. When the combined size of the current log file and the size of the provided byte slice is larger than the LogWriter's MaxBytes config argument, TODO. When a particular byte slice is longer than the LogWriter's MaxBytes config argument, the LogWriter will create a new file to hold the contents of the entire byte slice, regardless of its size, then will create a new output file the next time Write is invoked. Any time the LogWriter receives an error while attempting to roll the underlying output file, it simply writes the byte slice to the existing underlying file.