mlog

Documentation

Overview

Package mlog is a generic logging library. The log methods come in different severities: Debug, Info, Warn, Error, and Fatal.

The log methods take in a message string and a Context. The Context can be loaded with additional annotations which will be included in the log entry as well (see mctx package).

Index

• Variables
• func Truncate(s string, size int) string
• type FullMessage
• type Level
  • func LevelFromString(s string) Level
• type Logger
  • func NewLogger(opts *LoggerOpts) *Logger
  • func (l *Logger) Close() error
  • func (l *Logger) Debug(ctx context.Context, descr string)
  • func (l *Logger) Error(ctx context.Context, descr string, err error)
  • func (l *Logger) ErrorString(ctx context.Context, descr string)
  • func (l *Logger) Fatal(ctx context.Context, descr string, err error)
  • func (l *Logger) FatalString(ctx context.Context, descr string)
  • func (l *Logger) Info(ctx context.Context, descr string)
  • func (l *Logger) Log(msg Message)
  • func (l *Logger) MaxLevel() int
  • func (l *Logger) Warn(ctx context.Context, descr string, err error)
  • func (l *Logger) WarnString(ctx context.Context, descr string)
  • func (l *Logger) WithMaxLevel(level int) *Logger
  • func (l *Logger) WithNamespace(name string) *Logger
• type LoggerOpts
• type Message
• type MessageHandler
  • func NewMessageHandler(out io.Writer) MessageHandler

Variables

var Null = NewLogger(&LoggerOpts{
	MessageHandler: NewMessageHandler(ioutil.Discard),
})

Null is an instance of Logger which will write all Messages to /dev/null.

Functions

func Truncate

func Truncate(s string, size int) string

Truncate is a helper function to truncate a string to a given size. It will add 3 trailing elipses, so the returned string will be at most size+3 characters long

Types

type FullMessage

type FullMessage struct {
	Message
	Time      time.Time
	Namespace []string
}

FullMessage extends Message to contain loggable properties not provided directly by the user.

type Level

type Level interface {
	// String gives the string form of the level, e.g. "INFO" or "ERROR"
	String() string

	// Int gives an integer indicator of the severity of the level, with zero
	// being most severe. If a Level with a negative Int is logged then the
	// Logger implementation provided by this package will exit the process.
	Int() int
}

Level describes the severity of a particular log message, and can be compared to the severity of any other Level

var (
	LevelDebug Level = level{/* contains filtered or unexported fields */}
	LevelInfo  Level = level{/* contains filtered or unexported fields */}
	LevelWarn  Level = level{/* contains filtered or unexported fields */}
	LevelError Level = level{/* contains filtered or unexported fields */}
	LevelFatal Level = level{/* contains filtered or unexported fields */}
)

All pre-defined log levels

func LevelFromString

func LevelFromString(s string) Level

LevelFromString takes a string describing one of the pre-defined Levels (e.g. "debug" or "INFO") and returns the corresponding Level instance, or nil if the string doesn't describe any of the predefined Levels.

type Logger

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

Logger creates and directs Messages to an internal MessageHandler. All methods are thread-safe.

func NewLogger

func NewLogger(opts *LoggerOpts) *Logger

NewLogger initializes and returns a new instance of Logger.

func (*Logger) Close

func (l *Logger) Close() error

Close cleans up all resources held by the Logger.

func (*Logger) Debug

func (l *Logger) Debug(ctx context.Context, descr string)

Debug logs a LevelDebug message.

func (*Logger) Error

func (l *Logger) Error(ctx context.Context, descr string, err error)

Error logs a LevelError message, including information from the given error.

func (*Logger) ErrorString

func (l *Logger) ErrorString(ctx context.Context, descr string)

ErrorString logs a LevelError message which is only a string.

func (*Logger) Fatal

func (l *Logger) Fatal(ctx context.Context, descr string, err error)

Fatal logs a LevelFatal message. A Fatal message automatically stops the process with an os.Exit(1) if the default MessageHandler is used.

func (*Logger) FatalString

func (l *Logger) FatalString(ctx context.Context, descr string)

FatalString logs a LevelFatal message which is only a string. A Fatal message automatically stops the process with an os.Exit(1) if the default MessageHandler is used.

func (*Logger) Info

func (l *Logger) Info(ctx context.Context, descr string)

Info logs a LevelInfo message.

func (*Logger) Log

func (l *Logger) Log(msg Message)

Log can be used to manually log a message of some custom defined Level.

If the Level is a fatal (Int() < 0) then calling this will never return, and the process will have os.Exit(1) called.

func (*Logger) MaxLevel

func (l *Logger) MaxLevel() int

MaxLevel returns the Logger's maximum level which it will log (see MaxLevel in LoggerOpts, and the WithMaxLevel method).

func (*Logger) Warn

func (l *Logger) Warn(ctx context.Context, descr string, err error)

Warn logs a LevelWarn message, including information from the given error.

func (*Logger) WarnString

func (l *Logger) WarnString(ctx context.Context, descr string)

WarnString logs a LevelWarn message which is only a string.

func (*Logger) WithMaxLevel

func (l *Logger) WithMaxLevel(level int) *Logger

WithMaxLevel returns a clone of the Logger with the given MaxLevel set as the value for the maximum log level which will be output (see MaxLevel in LoggerOpts).

func (*Logger) WithNamespace

func (l *Logger) WithNamespace(name string) *Logger

WithNamespace returns a clone of the Logger with the given value appended to its namespace array. The namespace array is included in every FullMessage which is handled by Logger's MessageHandler.

type LoggerOpts

type LoggerOpts struct {
	// MessageHandler is the MessageHandler which will be used to process
	// Messages.
	//
	// Defaults to NewMessageHandler(os.Stderr).
	MessageHandler MessageHandler

	// MaxLevel indicates the maximum log level which should be handled. See the
	// Level interface for more.
	//
	// Defaults to LevelInfo.Int().
	MaxLevel int

	// Now returns the current time.Time whenever it is called.
	//
	// Defaults to time.Now.
	Now func() time.Time
}

LoggerOpts are optional parameters to NewLogger. All fields are optional. A nil value of LoggerOpts is equivalent to an empty one.

type Message

type Message struct {
	Context context.Context
	Level
	Description string
}

Message describes a message to be logged.

type MessageHandler

type MessageHandler interface {
	Handle(FullMessage) error

	// Sync flushes any buffered data to the handler's output, e.g. a file or
	// network connection. If the handler doesn't buffer data then this will be
	// a no-op.
	Sync() error
}

MessageHandler is a type which can process Messages in some way.

NOTE that Logger does not handle thread-safety, that must be done inside the MessageHandler if necessary.

func NewMessageHandler

func NewMessageHandler(out io.Writer) MessageHandler

NewMessageHandler initializes and returns a MessageHandler which will write all messages to the given io.Writer in a thread-safe way. If the io.Writer also implements a Sync or Flush method then that will be called when Sync is called on the returned MessageHandler.