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 SetLogger(cmp *mcmp.Component, l *Logger)
• func Truncate(s string, size int) string
• type Handler
  • func DefaultHandler() Handler
• type Level
  • func LevelFromString(s string) Level
• type Logger
  • func From(cmp *mcmp.Component) *Logger
  • func GetLogger(cmp *mcmp.Component) *Logger
  • func NewLogger() *Logger
  • func (l *Logger) Clone() *Logger
  • func (l *Logger) Debug(descr string, ctxs ...context.Context)
  • func (l *Logger) Error(descr string, ctxs ...context.Context)
  • func (l *Logger) Fatal(descr string, ctxs ...context.Context)
  • func (l *Logger) Handler() Handler
  • func (l *Logger) Info(descr string, ctxs ...context.Context)
  • func (l *Logger) Log(msg Message)
  • func (l *Logger) SetHandler(h Handler)
  • func (l *Logger) SetMaxLevel(lvl Level)
  • func (l *Logger) Warn(descr string, ctxs ...context.Context)
• type Message
• type MessageJSON

Variables

var DefaultLogger = NewLogger()

DefaultLogger is an instance of Logger which is returned by From when a Logger hasn't been previously set with SetLogger on the passed in Component.

Functions

func SetLogger

func SetLogger(cmp *mcmp.Component, l *Logger)

SetLogger sets the given logger onto the Component. The logger can later be retrieved from the Component, or any of its children, using From.

NOTE that if a Logger is set onto a Component and then changed, even though the Logger is a pointer and so is changed within the Component, SetLogger should still be called. This is due to some caching that From does for performance.

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 Handler

type Handler func(msg Message) error

Handler is a function which can process Messages in some way.

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

func DefaultHandler

func DefaultHandler() Handler

DefaultHandler initializes and returns a Handler which will write all messages to os.Stderr in a thread-safe way. This is the Handler which NewLogger will use automatically.

type Level

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

	// Uint gives an integer indicator of the severity of the level, with zero
	// being most severe. If a Level with Uint of zero is logged then the Logger
	// implementation provided by this package will exit the process (i.e. zero
	// is used as Fatal).
	Uint() uint
}

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

var (
	DebugLevel Level = level{/* contains filtered or unexported fields */}
	InfoLevel  Level = level{/* contains filtered or unexported fields */}
	WarnLevel  Level = level{/* contains filtered or unexported fields */}
	ErrorLevel Level = level{/* contains filtered or unexported fields */}
	FatalLevel 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 directs Messages to an internal Handler and provides convenient methods for creating and modifying its own behavior. All methods are thread-safe.

func From

func From(cmp *mcmp.Component) *Logger

From returns the result from GetLogger, modified so as to automatically add some annotations related to the Component itself to all Messages being logged.

func GetLogger

func GetLogger(cmp *mcmp.Component) *Logger

GetLogger returns the Logger which was set on the Component, or on of its ancestors, using SetLogger. If no Logger was ever set then DefaultLogger is returned.

func NewLogger

func NewLogger() *Logger

NewLogger initializes and returns a new instance of Logger which will write to the DefaultHandler.

func (*Logger) Clone

func (l *Logger) Clone() *Logger

Clone returns an identical instance of the Logger which can be modified independently of the original.

func (*Logger) Debug

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

Debug logs a DebugLevel message.

func (*Logger) Error

func (l *Logger) Error(descr string, ctxs ...context.Context)

Error logs a ErrorLevel message.

func (*Logger) Fatal

func (l *Logger) Fatal(descr string, ctxs ...context.Context)

Fatal logs a FatalLevel message. A Fatal message automatically stops the process with an os.Exit(1)

func (*Logger) Handler

func (l *Logger) Handler() Handler

Handler returns the Handler currently in use by the Logger.

func (*Logger) Info

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

Info logs a InfoLevel 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 (Uint() == 0) then calling this will never return, and the process will have os.Exit(1) called.

func (*Logger) SetHandler

func (l *Logger) SetHandler(h Handler)

SetHandler sets the Logger to use the given Handler in order to process Messages.

func (*Logger) SetMaxLevel

func (l *Logger) SetMaxLevel(lvl Level)

SetMaxLevel sets the Logger to not log any messages with a higher Level.Uint value than of the one given.

func (*Logger) Warn

func (l *Logger) Warn(descr string, ctxs ...context.Context)

Warn logs a WarnLevel message.

type Message

type Message struct {
	Level
	Description string
	Contexts    []context.Context
}

Message describes a message to be logged, after having already resolved the KVer

type MessageJSON

type MessageJSON struct {
	Level       string `json:"level"`
	Description string `json:"descr"`

	// key -> value
	Annotations map[string]string `json:"annotations,omitempty"`
}

MessageJSON is the type used to encode Messages to JSON in DefaultHandler