logging

Documentation

Overview

Package logging provides interfaces for consistent logging across packages.

Package logging provides interfaces for consistent logging across packages.

Index

• Variables
• type Destination
  • func ParseDestination(dest string) (Destination, error)
  • func (d *Destination) Validate() error
• type Format
  • func ParseFormat(format string) (Format, error)
  • func (f *Format) Validate() error
• type Level
  • func ParseLevel(level string) (Level, error)
  • func (l *Level) Validate() error
• type Logger
  • func New() *Logger
  • func NewWithRootLogger(underlyingLogger *logrus.Logger) *Logger
  • func (l *Logger) Debug(msg string)
  • func (l *Logger) Debugf(format string, args ...interface{})
  • func (l *Logger) Debugln(msg string)
  • func (l *Logger) Err(err error)
  • func (l *Logger) Error(msg string)
  • func (l *Logger) Errorf(format string, args ...interface{})
  • func (l *Logger) Errorln(msg string)
  • func (l *Logger) Info(msg string)
  • func (l *Logger) Infof(format string, args ...interface{})
  • func (l *Logger) Infoln(msg string)
  • func (l *Logger) Log(level Level, msg string)
  • func (l *Logger) Logf(level Level, format string, args ...interface{})
  • func (l *Logger) Logln(level Level, msg string)
  • func (l *Logger) Panic(msg string)
  • func (l *Logger) Panicf(format string, args ...interface{})
  • func (l *Logger) Panicln(msg string)
  • func (l *Logger) SetDestination(dest Destination) error
  • func (l *Logger) SetFormat(format Format) error
  • func (l *Logger) SetLevel(lvl Level) error
  • func (l *Logger) Trace(msg string)
  • func (l *Logger) Tracef(format string, args ...interface{})
  • func (l *Logger) Traceln(msg string)
  • func (l *Logger) Warning(msg string)
  • func (l *Logger) Warningf(format string, args ...interface{})
  • func (l *Logger) Warningln(msg string)
  • func (l Logger) WithHTTPRequest(req *http.Request, body []byte) *Logger
  • func (l Logger) WithHTTPResponse(res *http.Response, body []byte) *Logger
  • func (l Logger) WithSourceInfo(pkg, src, method string) *Logger
  • func (l Logger) WithTraceID(traceID TraceID) *Logger
• type TraceID
  • func NewTraceID() TraceID

Variables

var ErrInvalidDestination = errors.New("invalid destination")

ErrInvalidDestination is returned by Logger.SetDestination and Destination.Validate when provided an unknown underlying Destination value.

var ErrInvalidFormat = errors.New("invalid format")

ErrInvalidFormat is returned by Logger.SetFormat and Format.Validate when provided an unknown underlying Format value.

var ErrInvalidLevel = errors.New("invalid level")

ErrInvalidLevel is returned by Logger.SetLevel and Level.Validate when provided an unknown underlying Level value.

Types

type Destination

type Destination int

Destination represents the underlying filestream log messages will be written to.

const (

	// DestinationStdErr indicates logs should be written to os.StdErr.
	DestinationStdErr Destination

	// DestinationStdOut indicates logs should be written to os.StdOut.
	DestinationStdOut

	// DestinationNil indicates log messages should be silently dropped.
	DestinationNil
)

func ParseDestination

func ParseDestination(dest string) (Destination, error)

ParseDestination parses a string into a formal Destination. An unexpected or empty string will return ErrInvalidDestination.

func (*Destination) Validate

func (d *Destination) Validate() error

Validate returns ErrInvalidDestination if the Destination is destinationUnknown or anything other than a const provided by this package.

type Format

type Format int

Format is the format of written log messages.

const (

	// FormatJSON indicates logs should be written in JSON format.
	FormatJSON Format

	// FormatText indicates logs should be written in simple Text format. If
	// the Logger's configured Destination is connected to a TTY, logs will be
	// written in an easy-to-visually-parse format. Otherwise they are written
	// in the format expected by the system journal.
	FormatText
)

func ParseFormat

func ParseFormat(format string) (Format, error)

ParseFormat parses a string into a formal Format. An unexpected or empty string will return ErrInvalidFormat.

func (*Format) Validate

func (f *Format) Validate() error

Validate returns ErrInvalidFormat if the Format is FormatUnknown or anything other than a const provided by this package.

type Level

type Level int

Level is the syslog-esque logging level of a message.

const (

	// LevelTrace is the trace logging level. Trace log messages are typically
	// reserved for particularly in-depth log messages during a debugging dev
	// loop.
	LevelTrace Level

	// LevelDebug is the debug logging level. Debug log messages typically
	// provide low level detail of an individual unit of program input event.
	LevelDebug

	// LevelInfo is the info logging level. Info log messages typically provide
	// insight into the operational state of the process and the start and
	// outcome of an individual program input event.
	LevelInfo

	// LevelWarning is the warning logging level. Warning log messages
	// typically document recoverable or otherwise known unhappy-path states.
	LevelWarning

	// LevelError is the error logging level. Error log messages typically
	// document unrecoverable or otherwise extreme unhappy-path states.
	LevelError

	// LevelPanic is the panic logging level. Panic log messages document
	// a processes' imminent shutdown.
	LevelPanic
)

func ParseLevel

func ParseLevel(level string) (Level, error)

ParseLevel parses a string into a formal Level. An unexpected or empty string will return ErrInvalidLevel.

func (*Level) Validate

func (l *Level) Validate() error

Validate returns ErrInvalidLevel if the Level is LevelUnknown or anything other than a const provided by this package.

type Logger

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

A Logger provides methods for writing structured logs.

func New

func New() *Logger

New returns a new Logger with sensible defaults applied to the root logger.

func NewWithRootLogger

func NewWithRootLogger(underlyingLogger *logrus.Logger) *Logger

NewWithRootLogger returns a new Logger based on the given underlying logrus Logger. No defaults are applied.

func (*Logger) Debug

func (l *Logger) Debug(msg string)

Debug writes msg as a Debug log, suffixing a newline.

func (*Logger) Debugf

func (l *Logger) Debugf(format string, args ...interface{})

Debugf applies the given args to Printf-compatible format string and writes it as a Debug level log message.

func (*Logger) Debugln

func (l *Logger) Debugln(msg string)

Debugln writes msg as a Debug log, suffixing a newline.

func (*Logger) Err

func (l *Logger) Err(err error)

Err writes the given err as-is as an Error log if err is non-nil.

func (*Logger) Error

func (l *Logger) Error(msg string)

Error writes msg as a Error log, suffixing a newline.

func (*Logger) Errorf

func (l *Logger) Errorf(format string, args ...interface{})

Errorf applies the given args to Printf-compatible format string and writes it as a Error level log message.

func (*Logger) Errorln

func (l *Logger) Errorln(msg string)

Errorln writes msg as a Error log, suffixing a newline.

func (*Logger) Info

func (l *Logger) Info(msg string)

Info writes msg as a Info log, suffixing a newline.

func (*Logger) Infof

func (l *Logger) Infof(format string, args ...interface{})

Infof applies the given args to Printf-compatible format string and writes it as a Info level log message.

func (*Logger) Infoln

func (l *Logger) Infoln(msg string)

Infoln writes msg as a Info log, suffixing a newline.

func (*Logger) Log

func (l *Logger) Log(level Level, msg string)

Log writes msg as a Level log.

func (*Logger) Logf

func (l *Logger) Logf(level Level, format string, args ...interface{})

Logf applies the given args to Printf-compatible format string and writes it as a Level log message.

func (*Logger) Logln

func (l *Logger) Logln(level Level, msg string)

Logln writes msg as a Level log, suffixing a newline.

func (*Logger) Panic

func (l *Logger) Panic(msg string)

Panic writes msg as a Panic log, suffixing a newline.

func (*Logger) Panicf

func (l *Logger) Panicf(format string, args ...interface{})

Panicf applies the given args to Printf-compatible format string and writes it as a Panic level log message.

func (*Logger) Panicln

func (l *Logger) Panicln(msg string)

Panicln writes msg as a Panic log, suffixing a newline.

func (*Logger) SetDestination

func (l *Logger) SetDestination(dest Destination) error

SetDestination sets the given destination to all loggers descending from this instance's underlying logrus Logger. Providing a Destination that is not a const provided by this package will return an ErrInvalidDestination

func (*Logger) SetFormat

func (l *Logger) SetFormat(format Format) error

SetFormat sets the given formatter for log messages writen by any instance descending from the underlying logrus Logger. Providing a Formt that is not a const provided by this package will return an ErrInvalidFormat.

func (*Logger) SetLevel

func (l *Logger) SetLevel(lvl Level) error

SetLevel sets the logging level of all logger descending from this instance's underlying logrus Logger. Providing a Level that is not a const provided by this package will return an ErrInvalidLevel.

func (*Logger) Trace

func (l *Logger) Trace(msg string)

Trace writes msg as a Trace log, suffixing a newline.

func (*Logger) Tracef

func (l *Logger) Tracef(format string, args ...interface{})

Tracef applies the given args to Printf-compatible format string and writes it as a Trace level log message.

func (*Logger) Traceln

func (l *Logger) Traceln(msg string)

Traceln writes msg as a Trace log, suffixing a newline.

func (*Logger) Warning

func (l *Logger) Warning(msg string)

Warning writes msg as a Warning log, suffixing a newline.

func (*Logger) Warningf

func (l *Logger) Warningf(format string, args ...interface{})

Warningf applies the given args to Printf-compatible format string and writes it as a Warning level log message.

func (*Logger) Warningln

func (l *Logger) Warningln(msg string)

Warningln writes msg as a Warning log, suffixing a newline.

func (Logger) WithHTTPRequest

func (l Logger) WithHTTPRequest(req *http.Request, body []byte) *Logger

WithHTTPRequest attaches structured log fields about the given HTTP request and returns a reference to the value receiver. The body can optionally be logged as an attribute by providing a slice.

func (Logger) WithHTTPResponse

func (l Logger) WithHTTPResponse(res *http.Response, body []byte) *Logger

WithHTTPResponse attaches structured log fields about the given HTTP response and returns a reference to the value receiver. The body can optionally be logged as an attribute by providing a slice.

func (Logger) WithSourceInfo

func (l Logger) WithSourceInfo(pkg, src, method string) *Logger

WithSourceInfo attaches structured log fields describing the item making a log entry by its package, "source" (struct/interface/type), and method.

func (Logger) WithTraceID

func (l Logger) WithTraceID(traceID TraceID) *Logger

WithTraceID attaches a structured log field with the given trace ID.

type TraceID

type TraceID string

TraceID is a string for tying together log messages when an input causes activity across multiple services.

func NewTraceID

func NewTraceID() TraceID

NewTraceID returns a newly generated TraceID