handlers

package
v1.7.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 8, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package handlers holds the structural slog handlers this module composes chains from: Handler, which writes the process's own output, and FanOutHandler, which tees one record to many.

Destinations live in their own packages beside this one — handlers/logring for a searchable in-memory ring, handlers/loki for a Loki server. Those carry real API surface of their own; these two carry a type and a constructor each, which is why they sit here rather than in a subpackage apiece.

Index

Constants

View Source
const DefaultFormat = FormatText

DefaultFormat matches what slog itself does when you build a TextHandler by hand. JSON is the production choice; text is the one you want at a terminal.

View Source
const DefaultSplitLevel = slog.LevelWarn

DefaultSplitLevel is where records start going to stderr instead of stdout.

This is a deliberate departure from stdlib slog, which sends EVERY level to stderr. Splitting lets a container log collector keep error noise separate from happy-path noise without parsing anything.

Variables

View Source
var ErrInvalidFormat = errors.New("invalid log format")

Functions

This section is empty.

Types

type FanOutHandler

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

FanOutHandler tees one record to every handler it holds.

It holds the slog.Handler INTERFACE, not this package's Handler: that is what lets a searchable ring, a Loki client and anything a caller wrote themselves sit in the same chain. Narrowing it to a concrete type would make the fan-out useless for the sinks it exists to carry.

func NewFanOut

func NewFanOut(handlers ...slog.Handler) *FanOutHandler

NewFanOut creates a handler that dispatches to all the given handlers.

func (*FanOutHandler) Enabled

func (h *FanOutHandler) Enabled(ctx context.Context, level slog.Level) bool

Enabled reports whether ANY underlying handler wants records at this level.

Any, not all: a ring retaining DEBUG while the console sits at INFO is a normal setup, and the fan-out must not veto a record one of its children asked for. Each child re-checks its own level in Handle, so the noisier one does not force output on the quieter one.

func (*FanOutHandler) Handle

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

Handle dispatches the record to every underlying handler, and keeps going when one of them fails.

Returning at the first error would let a single broken sink silence all the ones after it: slog discards whatever Handle returns, so a Loki handler that cannot reach its server would take stdout down with it and nothing would say so. Every handler sees the record regardless of what the earlier ones did, and the failures are joined so none is lost.

func (*FanOutHandler) Handlers

func (h *FanOutHandler) Handlers() []slog.Handler

Handlers returns a copy of the dispatch list.

A copy, not the slice: handing out the backing array would let a caller reorder or nil an entry and silently change where the process logs. The copy is also what makes replace-slot-0 expressible from another package without exposing the field.

func (*FanOutHandler) Len

func (h *FanOutHandler) Len() int

Len reports how many handlers the fan-out dispatches to. Exported so callers can assert that adding a sink stacked onto the existing set rather than replacing it — the difference is invisible from the outside until logs go missing.

func (*FanOutHandler) WithAttrs

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

WithAttrs returns a FanOutHandler with the attrs added to every handler.

func (*FanOutHandler) WithGroup

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

WithGroup returns a FanOutHandler with the group applied to every handler.

type Format

type Format string

Format selects the wire shape of a record. It is a named type rather than a bare string so an unknown value is a compile-time mistake at every call site that uses the constants, and a single validated error everywhere else.

const (
	FormatJSON Format = "json"
	FormatText Format = "text"
)

type Handler

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

Handler is the process's output: every record goes to one of two writer sets, chosen by level.

Point both sets at the same writer and everything lands together, which is what stdlib slog does. Point them at different writers — the default — and warnings and errors are separable from the rest without parsing.

func New

func New(opts Options, writers ...Option) (*Handler, error)

New builds a Handler over the writers the options name, defaulting either side to the matching os stream when nothing named it.

Several writers on one side are joined with io.MultiWriter, so they all receive the same bytes. Different RENDERINGS per destination is a different job — build a Handler each and tee them with a FanOutHandler.

func NewStd

func NewStd(opts Options) (*Handler, error)

NewStd builds the conventional handler: stdout for informational records, stderr for warnings and above.

func (*Handler) Enabled

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

Enabled reports whether this handler emits records at the given level.

The Leveler is resolved HERE rather than captured at construction, so a *slog.LevelVar the caller bumps later actually takes effect. Storing the resolved slog.Level instead would silently ignore every later change.

func (*Handler) Handle

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

Handle writes the record to whichever side its level selects.

func (*Handler) WithAttrs

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

WithAttrs returns a Handler with the attrs bound to both sides.

func (*Handler) WithGroup

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

WithGroup returns a Handler with the group applied to both sides.

type Option

type Option func(*writerSet)

Option supplies writers to New. Stdout and Stderr are the two that exist; each is variadic, which is how a single call can name several writers per stream — Go allows only the FINAL parameter of a function to be variadic, so one constructor taking two variadic lists is not expressible.

func Stderr

func Stderr(w ...io.Writer) Option

Stderr appends writers to the stderr side.

func Stdout

func Stdout(w ...io.Writer) Option

Stdout appends writers to the stdout side.

type Options

type Options struct {
	// Format is the wire shape. Empty means DefaultFormat.
	Format Format

	// Level is the minimum level emitted. Nil means slog.LevelInfo.
	//
	// Hand it a *slog.LevelVar to be able to change the level at runtime; the
	// handler resolves it on every record rather than reading it once.
	Level slog.Leveler

	// AddSource attaches file/line/function to every record.
	AddSource bool

	// SplitAt is the level at and above which records go to stderr rather than
	// stdout. Nil means DefaultSplitLevel. Point both writer sets at the same
	// place and this stops mattering.
	SplitAt slog.Leveler
}

Options configures a Handler at construction.

Level is the only setting that stays live afterwards: it is a slog.Leveler, so passing a *slog.LevelVar and calling Set on it later changes what the handler emits from that moment on. Everything else is fixed once built.

Directories

Path Synopsis
Package logring keeps the most recent log records in a bounded in-memory ring so a process can search its own logs without leaving the process.
Package logring keeps the most recent log records in a bounded in-memory ring so a process can search its own logs without leaving the process.
Package loki pushes log records to Loki's HTTP API as an slog.Handler.
Package loki pushes log records to Loki's HTTP API as an slog.Handler.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL