mlog

Documentation

Overview

Package mlog provides advanced handlers for slog structured logging, in which log records include a message, a severity level, and various other attributes expressed as key-value pairs.

It defines a types HumanReadableHandler, MultipleHandler which provides additional functionality to the stdlib log/slog.

MultipleHandler

MultipleHandler allows to write one log event to multiple destinations. See `examples/multiple_destinations.go` to usage.

HumanReadableHandler

HumanReadableHandler is a alternative structured log representation where timestamp, level and message wrote as plain text line, but additional attributes show as JSON block.

A log record consists of a time, a level, a message, and a set of key-value pairs, where the keys are strings and the values may be of any type. As an example,

slog.Info("hello", "count", 3)

creates a record containing the time of the call, a level of Info, the message "hello", and a single pair with key "count" and value 3.

The default handler formats the log record's message, time, level, and attributes as a string and passes it to the log package.

2022/11/08 15:28:26 INFO hello count=3

For more control over the output format, create a logger with a different handler. This statement uses slog.New to create a new logger with a HumanReadableHandler that writes structured records in text form to standard error:

logger := slog.New(mlog.HumanReadableHandler(os.Stderr, nil))

HumanReadableHandler output is a sequence of timestamp, level and message as plain text to human readability and additional key=value pairs as JSON, easily and unambiguously parsed by machine. This statement:

logger.Info("hello", "count", 3)

produces this output:

2023-11-23T15:30:09.224406Z I --  hello  ATTRS={"count":3}

Setting a logger as the default with

slog.SetDefault(logger)

will cause the top-level functions like slog.Info to use it. slog.SetDefault also updates the default logger used by the log package, so that existing applications that use log.Printf and related functions will send log records to the logger's handler without needing to be rewritten.

Index

• Constants
• Variables
• func DecodeSource(pc uintptr) *slog.Source
• type HumanReadableHandler
  • func NewHumanReadableHandler(w io.Writer, opts *HumanReadableHandlerOptions) *HumanReadableHandler
  • func (h *HumanReadableHandler) Copy() *HumanReadableHandler
  • func (h *HumanReadableHandler) Enabled(_ context.Context, level slog.Level) bool
  • func (h *HumanReadableHandler) Handle(_ context.Context, r slog.Record) error
  • func (h *HumanReadableHandler) WithAttrs(aa []slog.Attr) slog.Handler
  • func (h *HumanReadableHandler) WithGroup(name string) slog.Handler
• type HumanReadableHandlerOptions
• type MultipleHandler
  • func NewMultipleHandler(_ *MultipleHandlerOptions, handlerSet ...slog.Handler) *MultipleHandler
  • func (h *MultipleHandler) Copy() *MultipleHandler
  • func (h *MultipleHandler) Enabled(_ context.Context, level slog.Level) bool
  • func (h *MultipleHandler) Handle(ctx context.Context, r slog.Record) error
  • func (h *MultipleHandler) WithAttrs(aa []slog.Attr) slog.Handler
  • func (h *MultipleHandler) WithGroup(name string) slog.Handler
• type MultipleHandlerOptions

Constants

const (
	TimeOutputFormatRFC3339 = "2006-01-02T15:04:05.000000Z07"
	LogLineBuffSize         = 1024
	AttrsJSONprefix         = "ATTRS="
)

Variables

var Error = errors.New("")

Functions

func DecodeSource

func DecodeSource(pc uintptr) *slog.Source

DecodeSource returns a new slog.Source which describes the location of a line of source code.

Types

type HumanReadableHandler

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

HumanReadableHandler is a slog.Handler that writes Records to an io.Writer as a timestamp, level, message as plain test, and sequence of key=value pairs in the JSON format and followed by a newline.

func NewHumanReadableHandler

func NewHumanReadableHandler(w io.Writer, opts *HumanReadableHandlerOptions) *HumanReadableHandler

NewHumanReadableHandler creates a HumanReadableHandler that writes to w, using the given options. If opts is nil, the default options are used. Implements slog.Handler interface.

func (*HumanReadableHandler) Copy

func (h *HumanReadableHandler) Copy() *HumanReadableHandler

func (*HumanReadableHandler) Enabled

func (h *HumanReadableHandler) Enabled(_ context.Context, level slog.Level) bool

Enabled reports whether the handler handles records at the given level. The handler ignores records whose level is lower. Implements slog.Handler interface.

func (*HumanReadableHandler) Handle

func (h *HumanReadableHandler) Handle(_ context.Context, r slog.Record) error

Handle handles the Record. It will only be called when Enabled(...) returns true. Implements slog.Handler interface.

func (*HumanReadableHandler) WithAttrs

func (h *HumanReadableHandler) WithAttrs(aa []slog.Attr) slog.Handler

WithAttrs returns a new HumanReadableHandler whose attributes consists of h's attributes followed by attrs. Implements slog.Handler interface.

func (*HumanReadableHandler) WithGroup

func (h *HumanReadableHandler) WithGroup(name string) slog.Handler

WithGroup returns a new HumanReadableHandler with the given group appended to the receiver's existing groups. Implements slog.Handler interface.

type HumanReadableHandlerOptions

type HumanReadableHandlerOptions struct {
	// AddSource causes the handler to compute the source code position
	// of the log statement and add source file name and line No to the output as plain text.
	AddSource bool

	// AddSourceToAttrs causes the handler to compute the source code position
	// of the log statement and add a "source" attribute to the ATTRS JSON block.
	AddSourceToAttrs bool

	UseLocalTZ bool

	// Level reports the minimum level to log.
	// Levels with lower levels are discarded.
	// If nil, the Handler uses [slog.LevelInfo].
	Level slog.Leveler
}

type MultipleHandler

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

MultipleHandler is a slog.Handler that multiply Records to each given handler as is.

func NewMultipleHandler

func NewMultipleHandler(_ *MultipleHandlerOptions, handlerSet ...slog.Handler) *MultipleHandler

NewMultipleHandler creates a MultipleHandler that multiply each incoming message to each given handler, using the given options. If opts is nil, the default options are used.

func (*MultipleHandler) Copy

func (h *MultipleHandler) Copy() *MultipleHandler

func (*MultipleHandler) Enabled

func (h *MultipleHandler) Enabled(_ context.Context, level slog.Level) bool

Enabled reports whether the handler handles records at the given level. The handler ignores records whose level is lower. Implements slog.Handler interface.

func (*MultipleHandler) Handle

func (h *MultipleHandler) Handle(ctx context.Context, r slog.Record) error

Handle handles the Record. It will only be called when Enabled(...) returns true. Implements slog.Handler interface.

func (*MultipleHandler) WithAttrs

func (h *MultipleHandler) WithAttrs(aa []slog.Attr) slog.Handler

WithAttrs returns a new HumanReadableHandler whose attributes consists of h's attributes followed by attrs. Implements slog.Handler interface.

func (*MultipleHandler) WithGroup

func (h *MultipleHandler) WithGroup(name string) slog.Handler

WithGroup returns a new HumanReadableHandler with the given group appended to the receiver's existing groups. Implements slog.Handler interface.

type MultipleHandlerOptions

type MultipleHandlerOptions struct{}

MultipleHandler currently has no options, but this will change in the future and the type is reserved to maintain backward compatibility