logging

Documentation

Overview

Package logging is an opinionated structured logging library based on log/slog.

This package also aliases most top-level functions in log/slog to reduce the need to manage the additional import.

Index

• Constants
• func FormatNames() []string
• func FromContext(ctx context.Context) *slog.Logger
• func LevelNames() []string
• func LevelSlogValue(l slog.Level) slog.Value
• func LevelString(l slog.Level) string
• func LookupLevel(name string) (slog.Level, error)
• func New(w io.Writer, logLevel, logFormat string, debug bool) (*slog.Logger, error)
• func SetLevel(logger *slog.Logger, level slog.Level) *slog.Logger
• func TestLogger(tb testing.TB) *slog.Logger
• func WithLogger(ctx context.Context, logger *slog.Logger) context.Context
• type Format
  • func LookupFormat(name string) (Format, error)
• type LevelHandler
  • func NewLevelHandler(leveler slog.Leveler, h slog.Handler) *LevelHandler
  • func (h *LevelHandler) Enabled(_ context.Context, level slog.Level) bool
  • func (h *LevelHandler) Handle(ctx context.Context, r slog.Record) error
  • func (h *LevelHandler) Handler() slog.Handler
  • func (h *LevelHandler) SetLevel(level slog.Level)
  • func (h *LevelHandler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (h *LevelHandler) WithGroup(name string) slog.Handler
• type LevelableHandler

Constants

const (
	FormatJSON = Format("JSON")
	FormatText = Format("TEXT")
)

const (
	LevelDebug     = slog.Level(-4)
	LevelInfo      = slog.Level(0)
	LevelNotice    = slog.Level(2)
	LevelWarning   = slog.Level(4)
	LevelError     = slog.Level(8)
	LevelEmergency = slog.Level(12)
)

Functions

func FormatNames

func FormatNames() []string

FormatNames returns the list of all log format names.

func FromContext

func FromContext(ctx context.Context) *slog.Logger

FromContext returns the logger stored in the context. If no such logger exists, a default logger is returned.

func LevelNames

func LevelNames() []string

LevelNames returns the list of all log level names.

func LevelSlogValue

func LevelSlogValue(l slog.Level) slog.Value

LevelSlogValue returns the slog.Value representation of the level.

func LevelString

func LevelString(l slog.Level) string

LevelString returns the string representation of the given level. Note this is different from calling String() on the Level, which uses the slog implementation.

func LookupLevel

func LookupLevel(name string) (slog.Level, error)

LookupLevel attempts to get the level that corresponds to the given name. If no such level exists, it returns an error. If the empty string is given, it returns Info level.

func New

func New(w io.Writer, logLevel, logFormat string, debug bool) (*slog.Logger, error)

New creates a new logger in the specified format and writes to the provided writer at the provided level. Use the returned leveler to dynamically change the level to a different value after creation.

If debug is true, the logging level is set to the lowest possible value (meaning all messages will be printed), and the output will include source information. This is very expensive, and you should not enable it unless actively debugging.

It returns the configured logger and a leveler which can be used to change the logger's level dynamically. The leveler does not require locking to change the level.

func SetLevel

func SetLevel(logger *slog.Logger, level slog.Level) *slog.Logger

SetLevel adjusts the level on the provided logger. The handler on the given logger must be a LevelableHandler or else this function panics. If you created a logger through this package, it will automatically satisfy that interface.

This function is safe for concurrent use.

It returns the provided logger for convenience and easier chaining.

func TestLogger

func TestLogger(tb testing.TB) *slog.Logger

TestLogger creates a new logger for use in tests. It will only log messages when tests fail and the tests were run with verbose (-v).

func WithLogger

func WithLogger(ctx context.Context, logger *slog.Logger) context.Context

WithLogger creates a new context with the provided logger attached.

Types

type Format

type Format string

Format represents the logging format.

func LookupFormat

func LookupFormat(name string) (Format, error)

LookupFormat attempts to get the formatter that corresponds to the given name. If no such formatter exists, it returns an error. If the empty string is given, it returns the JSON formatter.

type LevelHandler

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

LevelHandler is a wrapper around a LevelHandler that gives us the ability to configure level at runtime without users needing to manage a separate LevelVar.

func NewLevelHandler

func NewLevelHandler(leveler slog.Leveler, h slog.Handler) *LevelHandler

NewLevelHandler creates a new handler that is capable of dynamically setting a level in a concurrency-safe way.

func (*LevelHandler) Enabled

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

Enabled implements Handler.Enabled by reporting whether level is at least as large as h's level.

func (*LevelHandler) Handle

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

Handle implements Handler.Handle.

func (*LevelHandler) Handler

func (h *LevelHandler) Handler() slog.Handler

Handler returns the Handler wrapped by h.

func (*LevelHandler) SetLevel

func (h *LevelHandler) SetLevel(level slog.Level)

SetLevel implements the levelable interface. It adjusts the level of the logger. It is safe for concurrent use.

func (*LevelHandler) WithAttrs

func (h *LevelHandler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs implements Handler.WithAttrs.

func (*LevelHandler) WithGroup

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

WithGroup implements Handler.WithGroup.

type LevelableHandler

type LevelableHandler interface {
	// SetLevel dynamically sets the level on the handler.
	SetLevel(level slog.Level)
}

LevelableHandler is an interface which defines a handler that is able to dynamically set its level.