logging

Documentation

Overview

logging package defines loggers responsible for formatters log entries (delegated to Formatter) and delivering the formatted entries to whatever log destinations are needed.

Index

• type Container
• type Destination
• type Destinations
  • func (d *Destinations) Initialise() *Destinations
  • func (d *Destinations) Override(logLevel Level, destination Destination)
  • func (d *Destinations) SupportsLogLevel(logLevel Level) bool
  • func (d *Destinations) WithOverride(logLevel Level, destination Destination) *Destinations
• type Formatter
• type Level
• type Logger

Types

type Container

type Container interface {
	SetLogHandler(logger Logger)
	LogHandler() Logger
}

ContainedLogger defines an interface for users wishing to embed a Logger.

type Destination

type Destination io.Writer

Destination captures the output stream that a log should be written to.

var (
	DISCARD Destination = ioutil.Discard
	STDOUT  Destination = os.Stdout
	STDERR  Destination = os.Stderr
)

Three default Destination entries are provided by the package. DISCARD will cause the log entries to be written nowhere. STDOUT to standard console output, and STDERR for standard error console output.

type Destinations

type Destinations struct {
	Destinations map[Level]Destination
}

Destinations is a mapping of LogAtLevel values to Destination values.

func (*Destinations) Initialise

func (d *Destinations) Initialise() *Destinations

initialise creates and returns a Destinations instance with a default Destinations map. Specifically, DEBUG is discarded, INFO and WARN are delivered to STDOUT, and ERROR to STDERR.

func (*Destinations) Override

func (d *Destinations) Override(logLevel Level, destination Destination)

Override remaps the given LogLevelDestination's logLevel mapping to the new destination supplied.

func (*Destinations) SupportsLogLevel

func (d *Destinations) SupportsLogLevel(logLevel Level) bool

Override remaps the given LogLevelDestination's logLevel mapping to the new destination supplied.

func (*Destinations) WithOverride

func (d *Destinations) WithOverride(logLevel Level, destination Destination) *Destinations

WithOverride is a fluent method for overriding the existing Destinations map entry for logLevel to instead point to the new destination supplied.

type Formatter

type Formatter interface {
	// Format converts the supplied attributes into a representative 'observer ready' string.
	Format(attributes attributes.Attributes) string
}

Formatter describes an interface for the formatters of Attributes into some observer-ready string. Instances of Logger are expected to delegate any formatting of the supplied attributes to a Formatter.

type Level

type Level string

Level is a string identifier for a 'typical' set of log levels we might want to report against, ranging from DEBUG at the least critical/most noisy of log levels, to ERROR as the most critical/least noisy.

const (
	DEBUG Level = "Debug"
	INFO  Level = "Info"
	WARN  Level = "Warn"
	ERROR Level = "Error"
)

type Logger

type Logger interface {
	name.Nameable

	Debug(message interface{})
	Info(message interface{})
	Warn(message interface{})
	Error(message interface{})

	LogAtLevel(logLevel Level, message interface{})
	LogAtLevelWithAttributes(logLevel Level, attributes attributes.Attributes)

	Initialise()

	BeingDiscarded(logLevel Level) bool

	SetDestinations(*Destinations)
	Destinations() *Destinations

	SetFormatter(formatter Formatter)
	Formatter() Formatter

	SupportsLogLevel(logLevel Level) bool
	Override(logLevel Level, destination Destination)
}

Logger defines an interface for the handling of observer. It sets out methods for observer at the various supported LogLevels of either a free-form string (traditional), or Attributes (for machine-friendly observer). It delegates formatters to a Formatter, and resolution of log destination streams to Destinations.