Documentation

Overview

    Package logging provides interfaces for consistent logging across packages.

    Package logging provides interfaces for consistent logging across packages.

    Index

    Constants

    This section is empty.

    Variables

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

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

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

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

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

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

          Functions

          This section is empty.

          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