mlog

Documentation

Overview

Package mlog providers helpers on top of slog.Logger.

Packages of mox that are fit or use by external code take an *slog.Logger as parameter for logging. Internally, and packages not intended for reuse, logging is done with mlog.Log. It providers convenience functions for: logging error values, tracing (protocol messages), uncoditional printing optionally exiting.

An mlog provides a handler for an mlog.Log for formatting log lines. Lines are logged as "logfmt" lines for "mox serve". For command-line tools, the lines are printed with colon-separated level, message and error, followed by semicolon-separated attributes.

Index

• Variables
• func LogWriter(log Log, level slog.Level, msg string) io.Writer
• func SetConfig(c map[string]slog.Level)
• type Log
  • func New(pkg string, logger *slog.Logger) Log
  • func (l Log) Check(err error, msg string, attrs ...slog.Attr)
  • func (l Log) Debug(msg string, attrs ...slog.Attr)
  • func (l Log) Debugx(msg string, err error, attrs ...slog.Attr)
  • func (l Log) Error(msg string, attrs ...slog.Attr)
  • func (l Log) Errorx(msg string, err error, attrs ...slog.Attr)
  • func (l Log) Fatal(msg string, attrs ...slog.Attr)
  • func (l Log) Fatalx(msg string, err error, attrs ...slog.Attr)
  • func (l Log) Info(msg string, attrs ...slog.Attr)
  • func (l Log) Infox(msg string, err error, attrs ...slog.Attr)
  • func (l Log) Print(msg string, attrs ...slog.Attr)
  • func (l Log) Printx(msg string, err error, attrs ...slog.Attr)
  • func (l Log) Trace(level slog.Level, prefix string, data []byte)
  • func (l Log) Warn(msg string, attrs ...slog.Attr)
  • func (l Log) Warnx(msg string, err error, attrs ...slog.Attr)
  • func (l Log) With(attrs ...slog.Attr) Log
  • func (l Log) WithCid(cid int64) Log
  • func (l Log) WithContext(ctx context.Context) Log
  • func (l Log) WithFunc(fn func() []slog.Attr) Log
  • func (l Log) WithPkg(pkg string) Log
• type LogStringer

Variables

var (
	// When the configured log level is any of the Trace levels, all protocol messages
	// are printed. But protocol "data" (like an email message in the SMTP DATA
	// command) is replaced with "..." unless the configured level is LevelTracedata.
	// Likewise, protocol messages with authentication data (e.g. plaintext base64
	// passwords) are replaced with "***" unless the configured level is LevelTraceauth
	// or LevelTracedata.
	LevelTracedata = slog.LevelDebug - 8
	LevelTraceauth = slog.LevelDebug - 6
	LevelTrace     = slog.LevelDebug - 4
	LevelDebug     = slog.LevelDebug
	LevelInfo      = slog.LevelInfo
	LevelWarn      = slog.LevelWarn
	LevelError     = slog.LevelError
	LevelFatal     = slog.LevelError + 4 // Printed regardless of configured log level.
	LevelPrint     = slog.LevelError + 8 // Printed regardless of configured log level.
)

var CidKey key = "cid"

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

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

Levelstrings map log levels to human-readable names.

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

Levels map the human-readable log level to a level.

var Logfmt bool

Logfmt enabled output in logfmt, instead of output more suitable for command-line tools. Must be set early in a program lifecycle.

Functions

func LogWriter

func LogWriter(log Log, level slog.Level, msg string) io.Writer

LogWriter 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]slog.Level)

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

Types

type Log

type Log struct {
	*slog.Logger
}

Log wraps an slog.Logger, providing convenience functions.

func New

func New(pkg string, logger *slog.Logger) Log

New returns a Log that adds a "pkg" attribute. If logger is nil, a new Logger is created with a custom handler.

func (Log) Check

func (l Log) Check(err error, msg string, attrs ...slog.Attr)

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(msg string, attrs ...slog.Attr)

func (Log) Debugx

func (l Log) Debugx(msg string, err error, attrs ...slog.Attr)

func (Log) Error

func (l Log) Error(msg string, attrs ...slog.Attr)

func (Log) Errorx

func (l Log) Errorx(msg string, err error, attrs ...slog.Attr)

func (Log) Fatal

func (l Log) Fatal(msg string, attrs ...slog.Attr)

func (Log) Fatalx

func (l Log) Fatalx(msg string, err error, attrs ...slog.Attr)

func (Log) Info

func (l Log) Info(msg string, attrs ...slog.Attr)

func (Log) Infox

func (l Log) Infox(msg string, err error, attrs ...slog.Attr)

func (Log) Print

func (l Log) Print(msg string, attrs ...slog.Attr)

func (Log) Printx

func (l Log) Printx(msg string, err error, attrs ...slog.Attr)

func (Log) Trace

func (l Log) Trace(level slog.Level, prefix string, data []byte)

Trace logs at trace/traceauth/tracedata level. If the active log level is any of the trace levels, the data is logged. If level is for tracedata, but the active level doesn't trace data, data is replaced with "...". If level is for traceauth, but the active level doesn't trace auth, data is replaced with "***".

func (Log) Warn

func (l Log) Warn(msg string, attrs ...slog.Attr)

func (Log) Warnx

func (l Log) Warnx(msg string, err error, attrs ...slog.Attr)

func (Log) With

func (l Log) With(attrs ...slog.Attr) Log

With adds attributes to to each logged line.

func (Log) WithCid

func (l Log) WithCid(cid int64) Log

WithCid adds a attribute "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 logger, with WithContext for its cid. Ideally, a Log could be passed instead, but contexts are more pervasive. For the same reason WithContext is more common than WithCid.

func (Log) WithFunc

func (l Log) WithFunc(fn func() []slog.Attr) Log

WithFunc sets fn to be called for additional attributes. Fn is only called when the line is logged. If the underlying handler is not an mlog.handler, this method has no effect. Caller must take care of preventing data races.

func (Log) WithPkg

func (l Log) WithPkg(pkg string) Log

WithPkg ensures pkg is added as attribute to logged lines. If the handler is an mlog handler, pkg is only added if not already the last added package.

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.