mlog

Documentation

Overview

Package mlog provides logging with log levels and fields.

Each log level has a function to log with and without error. Each such function takes a varargs list of fields (key value pairs) to log. Variable data should be in fields. Logging strings themselves should be constant, for easier log processing (e.g. building metrics based on log messages).

The log levels can be configured per originating package, e.g. smtpclient, imapserver. The configuration is application-global, so each Log instance uses the same log levels.

Print* should be used for lines that always should be printed, regardless of configured log levels. Useful for startup logging and subcommands.

Fatal* stops the program. Its log text is always printed.

Index

• Variables
• func ErrWriter(log *Log, level Level, msg string) io.Writer
• func SetConfig(c map[string]Level)
• type Level
  • func (l Level) String() string
• type Log
  • func New(pkg string) *Log
  • func (l *Log) Check(err error, text string, fields ...Pair)
  • func (l *Log) Debug(text string, fields ...Pair) bool
  • func (l *Log) Debugx(text string, err error, fields ...Pair) bool
  • func (l *Log) Error(text string, fields ...Pair) bool
  • func (l *Log) Errorx(text string, err error, fields ...Pair) bool
  • func (l *Log) Fatal(text string, fields ...Pair)
  • func (l *Log) Fatalx(text string, err error, fields ...Pair)
  • func (l *Log) Fields(fields ...Pair) *Log
  • func (l *Log) Info(text string, fields ...Pair) bool
  • func (l *Log) Infox(text string, err error, fields ...Pair) bool
  • func (l *Log) MoreFields(fn func() []Pair) *Log
  • func (l *Log) Print(text string, fields ...Pair) bool
  • func (l *Log) Printx(text string, err error, fields ...Pair) bool
  • func (l *Log) Trace(traceLevel Level, text string) bool
  • func (l *Log) WithCid(cid int64) *Log
  • func (l *Log) WithContext(ctx context.Context) *Log
• type LogStringer
• type Pair
  • func Field(k string, v any) Pair

Variables

var CidKey key = "cid"

CidKey can be used with context.WithValue to store a "cid" in a context, for logging.

var LevelStrings = map[Level]string{
	LevelPrint:     "print",
	LevelFatal:     "fatal",
	LevelError:     "error",
	LevelInfo:      "info",
	LevelDebug:     "debug",
	LevelTrace:     "trace",
	LevelTraceauth: "traceauth",
	LevelTracedata: "tracedata",
}

var Levels = map[string]Level{
	"print":     LevelPrint,
	"fatal":     LevelFatal,
	"error":     LevelError,
	"info":      LevelInfo,
	"debug":     LevelDebug,
	"trace":     LevelTrace,
	"traceauth": LevelTraceauth,
	"tracedata": LevelTracedata,
}

var Logfmt bool

Functions

func ErrWriter

func ErrWriter(log *Log, level Level, msg string) io.Writer

ErrWriter returns a writer that turns each write into a logging call on "log" with given "level" and "msg" and the written content as an error. Can be used for making a Go log.Logger for use in http.Server.ErrorLog.

func SetConfig

func SetConfig(c map[string]Level)

SetConfig atomically sets the new log levels used by all Log instances.

Types

type Level

type Level int

const (
	LevelPrint     Level = 0 // Printed regardless of configured log level.
	LevelFatal     Level = 1 // Printed regardless of configured log level.
	LevelError     Level = 2
	LevelInfo      Level = 3
	LevelDebug     Level = 4
	LevelTrace     Level = 5
	LevelTraceauth Level = 6
	LevelTracedata Level = 7
)

func (Level) String

func (l Level) String() string

type Log

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

Log is an instance potentially with its own field/value pair added to any logging output.

func New

func New(pkg string) *Log

New returns a new Log instance. Each log invocation adds field "pkg".

func (*Log) Check

func (l *Log) Check(err error, text string, fields ...Pair)

Check logs an error if err is not nil. Intended for logging errors that are good to know, but would not influence program flow.

func (*Log) Debug

func (l *Log) Debug(text string, fields ...Pair) bool

func (*Log) Debugx

func (l *Log) Debugx(text string, err error, fields ...Pair) bool

func (*Log) Error

func (l *Log) Error(text string, fields ...Pair) bool

func (*Log) Errorx

func (l *Log) Errorx(text string, err error, fields ...Pair) bool

func (*Log) Fatal

func (l *Log) Fatal(text string, fields ...Pair)

func (*Log) Fatalx

func (l *Log) Fatalx(text string, err error, fields ...Pair)

func (*Log) Fields

func (l *Log) Fields(fields ...Pair) *Log

Field adds fields to the logger. Each logged line adds these fields.

func (*Log) Info

func (l *Log) Info(text string, fields ...Pair) bool

func (*Log) Infox

func (l *Log) Infox(text string, err error, fields ...Pair) bool

func (*Log) MoreFields

func (l *Log) MoreFields(fn func() []Pair) *Log

MoreFields sets a function on the logger that is called just before logging, to retrieve additional fields to log.

func (*Log) Print

func (l *Log) Print(text string, fields ...Pair) bool

func (*Log) Printx

func (l *Log) Printx(text string, err error, fields ...Pair) bool

func (*Log) Trace

func (l *Log) Trace(traceLevel Level, text string) bool

func (*Log) WithCid

func (l *Log) WithCid(cid int64) *Log

WithCid adds a field "cid". Also see WithContext.

func (*Log) WithContext

func (l *Log) WithContext(ctx context.Context) *Log

WithContext adds cid from context, if present. Context are often passed to functions, especially between packages, to pass a "cid" for an operation. At the start of a function (especially if exported) a variable "log" is often instantiated from a package-level variable "xlog", with WithContext for its cid. A *Log could be passed instead, but contexts are more pervasive. For the same reason WithContext is more common than WithCid.

type LogStringer

type LogStringer interface {
	LogString() string
}

LogStringer is used when formatting field values during logging. If a value implements it, LogString is called for the value to log.

type Pair

type Pair struct {
	Key   string
	Value any
}

Pair is a field/value pair, for use in logged lines.

func Field

func Field(k string, v any) Pair

Field is a shorthand for making a Pair.