logging

Documentation

Overview

Package logging provides basic configurability for the go-kit/log packages.

Index

• Constants
• func CallerKey() interface{}
• func Debug(next log.Logger, keyvals ...interface{}) log.Logger
• func DefaultCaller(next log.Logger, keyvals ...interface{}) log.Logger
• func DefaultLogger() log.Logger
• func Enrich(logger log.Logger, objects ...interface{}) log.Logger
• func EnrichPrefix(logger log.Logger, objects ...interface{}) log.Logger
• func Error(next log.Logger, keyvals ...interface{}) log.Logger
• func ErrorKey() interface{}
• func GetLogger(ctx context.Context) log.Logger
• func Info(next log.Logger, keyvals ...interface{}) log.Logger
• func MessageKey() interface{}
• func New(o *Options) log.Logger
• func NewFilter(next log.Logger, o *Options) log.Logger
• func NewTestLogger(o *Options, t testSink) log.Logger
• func NewTestWriter(t testSink) io.Writer
• func Sub(v *viper.Viper) *viper.Viper
• func TimestampKey() interface{}
• func Warn(next log.Logger, keyvals ...interface{}) log.Logger
• func WithLogger(parent context.Context, logger log.Logger) context.Context
• type CaptureLogger
  • func NewCaptureLogger() CaptureLogger
• type Contextual
• type Options
  • func FromViper(v *viper.Viper) (*Options, error)

Constants

const (
	// LoggingKey is the Viper subkey under which logging should be stored.
	// NewOptions *does not* assume this key.
	LoggingKey = "log"
)

const (
	StdoutFile = "stdout"
)

Functions

func CallerKey

func CallerKey() interface{}

CallerKey returns the logging key to be used for the stack location of the logging call

func Debug

func Debug(next log.Logger, keyvals ...interface{}) log.Logger

Debug places both the caller and a constant debug level into the prefix of the returned logger. Additional key value pairs may also be added.

func DefaultCaller

func DefaultCaller(next log.Logger, keyvals ...interface{}) log.Logger

DefaultCaller produces a contextual logger as with log.With, but automatically prepends the caller under the CallerKey.

The logger returned by this function should not be further decorated. This will cause the callstack to include the decorators, which is pointless. Instead, decorate the next parameter prior to passing it to this function.

func DefaultLogger

func DefaultLogger() log.Logger

DefaultLogger returns a global singleton NOP logger. This returned instance is safe for concurrent access.

func Enrich

func Enrich(logger log.Logger, objects ...interface{}) log.Logger

Enrich uses log.With to add contextual information to a logger. The given set of objects are examined to see if they contain any metadata. Objects that do not contain metadata are simply ignored.

An object contains metadata if it implements Contextual, is a map[string]interface{}, or is a map[string]string. In those cases, the key/value pairs are present in the returned logger.

func EnrichPrefix

func EnrichPrefix(logger log.Logger, objects ...interface{}) log.Logger

EnrichPrefix is like Enrich, except that it uses log.WithPrefix.

func Error

func Error(next log.Logger, keyvals ...interface{}) log.Logger

Error places both the caller and a constant error level into the prefix of the returned logger. Additional key value pairs may also be added.

func ErrorKey

func ErrorKey() interface{}

ErrorKey returns the logging key to be used for error instances

func GetLogger

func GetLogger(ctx context.Context) log.Logger

GetLogger retrieves the go-kit logger associated with the context. If no logger is present in the context, DefaultLogger is returned instead.

func Info

func Info(next log.Logger, keyvals ...interface{}) log.Logger

Info places both the caller and a constant info level into the prefix of the returned logger. Additional key value pairs may also be added.

func MessageKey

func MessageKey() interface{}

MessageKey returns the logging key to be used for the textual message of the log entry

func New

func New(o *Options) log.Logger

New creates a go-kit Logger from a set of options. The options object can be nil, in which case a default logger that logs to os.Stdout is returned. The returned logger includes the timestamp in UTC format and will filter according to the Level field.

In order to allow arbitrary decoration, this function does not insert the caller information. Use either DefaultCaller in this package or the go-kit/kit/log API to add a Caller to the returned Logger.

func NewFilter

func NewFilter(next log.Logger, o *Options) log.Logger

NewFilter applies the Options filtering rules in the package to an arbitrary go-kit Logger.

func NewTestLogger

func NewTestLogger(o *Options, t testSink) log.Logger

NewTestLogger produces a go-kit Logger which delegates to the supplied testing log.

func NewTestWriter

func NewTestWriter(t testSink) io.Writer

NewTestWriter returns an io.Writer which delegates to a testing log. The returned io.Writer does not need to be synchronized.

func Sub

func Sub(v *viper.Viper) *viper.Viper

Sub returns the standard child Viper, using LoggingKey, for this package. If passed nil, this function returns nil.

func TimestampKey

func TimestampKey() interface{}

TimestampKey returns the logging key to be used for the timestamp

func Warn

func Warn(next log.Logger, keyvals ...interface{}) log.Logger

Warn places both the caller and a constant warn level into the prefix of the returned logger. Additional key value pairs may also be added.

func WithLogger

func WithLogger(parent context.Context, logger log.Logger) context.Context

WithLogger adds the given Logger to the context so that it can be retrieved with Logger

Types

type CaptureLogger

type CaptureLogger interface {
	log.Logger

	// Output returns the channel on which each log event is recorded as a map of key/value pairs
	Output() <-chan map[interface{}]interface{}
}

CaptureLogger is a go-kit Logger which dispatches log key/value pairs to a channel for test assertions and verifications. Primarily useful for test code.

The Log method of this type will panic if the number of key/value pairs is not odd, which is appropriate for test code.

func NewCaptureLogger

func NewCaptureLogger() CaptureLogger

type Contextual

type Contextual interface {
	Metadata() map[string]interface{}
}

Contextual describes an object which can describe itself with metadata for logging. Implementing this interface allows code to carry logging context data across API boundaries without compromising encapsulation.

type Options

type Options struct {
	// File is the system file path for the log file.  If set to "stdout", this will log to os.Stdout.
	// Otherwise, a lumberjack.Logger is created
	File string `json:"file"`

	// MaxSize is the lumberjack MaxSize
	MaxSize int `json:"maxsize"`

	// MaxAge is the lumberjack MaxAge
	MaxAge int `json:"maxage"`

	// MaxBackups is the lumberjack MaxBackups
	MaxBackups int `json:"maxbackups"`

	// JSON is a flag indicating whether JSON logging output is used.  The default is false,
	// meaning that logfmt output is used.
	JSON bool `json:"json"`

	// Level is the error level to output: ERROR, INFO, WARN, or DEBUG.  Any unrecognized string,
	// including the empty string, is equivalent to passing ERROR.
	Level string `json:"level"`
}

Options stores the configuration of a Logger. Lumberjack is used for rolling files.

func FromViper

func FromViper(v *viper.Viper) (*Options, error)

FromViper produces an Options from a (possibly nil) Viper instance. Callers should use FromViper(Sub(v)) if the standard subkey is desired.