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
- Variables
- type FanOutHandler
- func (h *FanOutHandler) Enabled(ctx context.Context, level slog.Level) bool
- func (h *FanOutHandler) Handle(ctx context.Context, r slog.Record) error
- func (h *FanOutHandler) Handlers() []slog.Handler
- func (h *FanOutHandler) Len() int
- func (h *FanOutHandler) WithAttrs(attrs []slog.Attr) slog.Handler
- func (h *FanOutHandler) WithGroup(name string) slog.Handler
- type Format
- type Handler
- type Option
- type Options
Constants ¶
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.
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 ¶
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 ¶
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 ¶
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.
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.
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 ¶
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 ¶
NewStd builds the conventional handler: stdout for informational records, stderr for warnings and above.
func (*Handler) Enabled ¶
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.
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.
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. |