log

README

log

This package allows developers to easily create structured, leveled logs.

Installation

This package was written in the Go programming language. Once you have Go installed, you can install this package by issuing the following command.

go get github.com/forestgiant/log

Once the command above has finished, you should be able to import the package for use in your own code as follows.

import "github.com/forestgiant/log"

Log Levels

This package provides convenience methods which log at the following levels. When these methods are used, the corresponding levels are automatically associated with the level key in the log output.

• Alert - alert
• Critical - critical
• Debug - debug
• Emergency - emergency
• Error - error
• Info - info
• Notice - notice
• Warning - warning

Log Formats

This package provides Formatter implementations capable of structuring logs in the following formats. If you would prefer to use an alternate format, you can implement the Formatter interface and provide your custom Formatter to the Logger.

• JSON - default
• logfmt

Log Output

By default, this package will log to os.Stdout. If you would prefer, output can be written to an alternate io.Writer.

Context

Each Logger has a series of key-value pairs that make up it's context. If values exist in the Logger's context, these values will be present in the log output.

Value Generators

Unlike most values that are added to a Logger's context, a ValueGenerator is a function that will be evaluated at the time the log entry is formatted. This is useful in scenarios where you may want to provide some runtime context to your logs, such as line numbers or timestamps.

Documentation and Examples

If you need more information, please check out our GoDoc page. You will find a number of examples on that page that should help understand how this package can best be used. If you notice anything out of place or undocumented, be sure to let us know!

Inspiration

This package was largely based on Go kit's log package. Through reading the source, as well as a number of conversations they pointed out in their GitHub issues, I feel I was able to get a much better grasp on the topic of structured logging in general. I'd like to extend my thanks to that team for having made such a great resource!

Documentation

Index

• Variables
• type Formatter
• type JSONFormatter
  • func (f JSONFormatter) Format(writer io.Writer, keyvals ...interface{}) error
• type LogfmtFormatter
  • func (f LogfmtFormatter) Format(writer io.Writer, keyvals ...interface{}) error
• type Logger
  • func (l *Logger) Alert(message string, keyvals ...interface{}) error
  • func (l *Logger) Critical(message string, keyvals ...interface{}) error
  • func (l *Logger) Debug(message string, keyvals ...interface{}) error
  • func (l *Logger) Emergency(message string, keyvals ...interface{}) error
  • func (l *Logger) Error(message string, keyvals ...interface{}) error
  • func (l *Logger) Info(message string, keyvals ...interface{}) error
  • func (l *Logger) Notice(message string, keyvals ...interface{}) error
  • func (l *Logger) Warning(message string, keyvals ...interface{}) error
  • func (l Logger) With(keyvals ...interface{}) Logger
• type ValueGenerator
  • func Caller(depth int) ValueGenerator

Examples

• Logger
• Logger (Context)
• Logger (Logfmt)
• Logger (ValueGenerator)
• Logger (Writer)
• Logger.Alert
• Logger.Critical
• Logger.Debug
• Logger.Emergency
• Logger.Error
• Logger.Info
• Logger.Notice
• Logger.Warning

Variables

var DefaultCaller = Caller(5)

DefaultCaller is a Callert with a depth that corresponds to the first call outside of this package

var ErrIgnoredLogLevel = errors.New("Log level is ignored by the logger")

ErrIgnoredLogLevel is the error returned when a logger ignores the log at the current level configuration

Types

type Formatter

type Formatter interface {
	Format(writer io.Writer, keyvals ...interface{}) error
}

Formatter is a simple interface for formatting messages written to an io.Writer

type JSONFormatter

type JSONFormatter struct{}

JSONFormatter implements the LogFormatter interface for JSON outpiut

func (JSONFormatter) Format

func (f JSONFormatter) Format(writer io.Writer, keyvals ...interface{}) error

Format will write the provided key-value pairs to the specified io.Writer in JSON format

type LogfmtFormatter

type LogfmtFormatter struct{}

LogfmtFormatter implements the LogFormatter interface for Logfmt outpiut

func (LogfmtFormatter) Format

func (f LogfmtFormatter) Format(writer io.Writer, keyvals ...interface{}) error

Format will write the provided key-value pairs to the specified io.Writer in Logfmt format

type Logger

type Logger struct {
	Writer    io.Writer
	Formatter Formatter

	FilterLevel int
	// contains filtered or unexported fields
}

Logger implements the Logger interface as well as some helper methods for leveled logging.

Example

logger := Logger{}
logger.Info("Info level log message", "key", "value")

Output:

{"key":"value","level":"info","msg":"Info level log message"}

Example (Context)

logger := Logger{}.With("key", "value")
logger.Info("Info level log message")

Output:

{"key":"value","level":"info","msg":"Info level log message"}

Example (Logfmt)

logger := Logger{Formatter: LogfmtFormatter{}}
logger.Info("Info level log message", "key", "value")

Output:

level=info msg="Info level log message" key=value

Example (ValueGenerator)

var v ValueGenerator = func() interface{} {
	return "generated"
}
logger := Logger{}.With("key", v)
logger.Info("Info level log message")

Output:

{"key":"generated","level":"info","msg":"Info level log message"}

Example (Writer)

buffer := &bytes.Buffer{}
logger := Logger{Writer: buffer}
logger.Info("Info level log message", "key", "value")

func (*Logger) Alert

func (l *Logger) Alert(message string, keyvals ...interface{}) error

Alert logs the provided key value pairs, adding the alert log level

Example

logger := Logger{}
logger.Alert("Alert level log message", "key", "value")

Output:

{"key":"value","level":"alert","msg":"Alert level log message"}

func (*Logger) Critical

func (l *Logger) Critical(message string, keyvals ...interface{}) error

Critical logs the provided key value pairs, adding the critical log level

Example

logger := Logger{}
logger.Critical("Critical level log message", "key", "value")

Output:

{"key":"value","level":"critical","msg":"Critical level log message"}

func (*Logger) Debug

func (l *Logger) Debug(message string, keyvals ...interface{}) error

Debug logs the provided key value pairs, adding the debug log level

Example

logger := Logger{}
logger.Debug("Debug level log message", "key", "value")

Output:

{"key":"value","level":"debug","msg":"Debug level log message"}

func (*Logger) Emergency

func (l *Logger) Emergency(message string, keyvals ...interface{}) error

Emergency logs the provided key value pairs, adding the emergency log level

Example

logger := Logger{}
logger.Emergency("Emergency level log message", "key", "value")

Output:

{"key":"value","level":"emergency","msg":"Emergency level log message"}

func (*Logger) Error

func (l *Logger) Error(message string, keyvals ...interface{}) error

Error logs the provided key value pairs, adding the error log level

Example

logger := Logger{}
logger.Error("Error level log message", "key", "value")

Output:

{"key":"value","level":"error","msg":"Error level log message"}

func (*Logger) Info

func (l *Logger) Info(message string, keyvals ...interface{}) error

Info logs the provided key value pairs, adding the info log level

Example

logger := Logger{}
logger.Info("Info level log message", "key", "value")

Output:

{"key":"value","level":"info","msg":"Info level log message"}

func (*Logger) Notice

func (l *Logger) Notice(message string, keyvals ...interface{}) error

Notice logs the provided key value pairs, adding the notice log level

Example

logger := Logger{}
logger.Notice("Notice level log message", "key", "value")

Output:

{"key":"value","level":"notice","msg":"Notice level log message"}

func (*Logger) Warning

func (l *Logger) Warning(message string, keyvals ...interface{}) error

Warning logs the provided key value pairs, adding the warning log level

Example

logger := Logger{}
logger.Warning("Warning level log message", "key", "value")

Output:

{"key":"value","level":"warning","msg":"Warning level log message"}

func (Logger) With

func (l Logger) With(keyvals ...interface{}) Logger

With returns a copy of the logger with the provided key-value pairs to the backing context

type ValueGenerator

type ValueGenerator func() interface{}

A ValueGenerator is a function that generates a dynamic value to be evaluated at the time of a log event

var DefaultTimestamp ValueGenerator = func() interface{} {
	return time.Now().Format(time.RFC3339)
}

DefaultTimestamp is a ValueGenerator that returns the current time in RFC3339 format

func Caller

func Caller(depth int) ValueGenerator

Caller is a ValueGenerator that returns the file and line number where the log event originated