logging

Documentation

Overview

Package logging provides a single, uniform structured-logging entrypoint shared by every binary in the multicast fleet (shard-proxy, shard-listener, retry-endpoint, shard-manifest, subtx-generator).

It owns slog initialisation so the previously divergent per-service setup sites collapse to one Init call. Every log line emitted after Init carries the same identity triple that OTLP metrics attach as resource attributes (service.name, service.instance.id, service.version), so logs and metrics join on shared dimensions in the backend.

Output contract (see bsv-multicast/docs/UnifiedLogging/unified-logging-plan.md):

• FormatJSON writes one JSON object per line to stdout (12-factor; the process emits, the collector ships).
• FormatText writes human-readable lines to stderr (interactive/dev default).

The returned *slog.LevelVar lets an operator change the level at runtime (SIGHUP toggle via InstallSIGHUPToggle or an admin endpoint via LevelHandler) without a restart.

Index

• func Init(opts Options) *slog.LevelVar
• func InstallSIGHUPToggle(lvl *slog.LevelVar, base slog.Level) (stop func())
• func LevelHandler(lvl *slog.LevelVar) http.HandlerFunc
• func ParseLevel(s string) slog.Level
• type Format
  • func ParseFormat(s string) Format
• type Options
• type Throttle
  • func NewThrottle(window time.Duration) *Throttle
  • func (t *Throttle) Allow(key string) (emit bool, suppressed uint64)

Functions

func Init

func Init(opts Options) *slog.LevelVar

Init installs a process-wide slog default with the identity triple pre-attached and returns a *slog.LevelVar whose level can be changed at runtime. It is safe to call before config parsing (the pre-config error path can rely on the slog default already being usable).

func InstallSIGHUPToggle

func InstallSIGHUPToggle(lvl *slog.LevelVar, base slog.Level) (stop func())

InstallSIGHUPToggle wires SIGHUP to toggle between base and slog.LevelDebug. The first SIGHUP enables debug; the next restores base, and so on. It returns a stop func that unregisters the handler. base is typically the configured startup level.

func LevelHandler

func LevelHandler(lvl *slog.LevelVar) http.HandlerFunc

LevelHandler returns an http.HandlerFunc for runtime level inspection and change, intended to be mounted on the existing metrics/admin listener.

GET  -> returns the current level as text (e.g. "INFO")
PUT/POST ?level=debug -> sets the level; returns the new level

This lets an operator drop one hot host to debug without a restart.

func ParseLevel

func ParseLevel(s string) slog.Level

ParseLevel maps a config string (debug|info|warn|error) to an slog.Level. Unknown values fall back to LevelInfo.

Types

type Format

type Format int

Format selects the output encoding.

const (
	// FormatText is human-readable key=value output (default; stderr).
	FormatText Format = iota
	// FormatJSON is one JSON object per line (fleet/aggregation; stdout).
	FormatJSON
)

func ParseFormat

func ParseFormat(s string) Format

ParseFormat maps a config string to a Format. Unknown values fall back to FormatText.

type Options

type Options struct {
	// Service is the OTel service.name; MUST equal the metrics package's
	// ServiceName for the same binary so logs and metrics share identity.
	Service string
	// InstanceID is the OTel service.instance.id (hostname/pod name). Empty
	// falls back to os.Hostname().
	InstanceID string
	// Version is the build version (matches metrics.Version).
	Version string
	// Level is the initial log level.
	Level slog.Level
	// Format selects the encoding.
	Format Format
	// Output overrides the sink. When nil, FormatJSON uses stdout and
	// FormatText uses stderr.
	Output io.Writer
}

Options configures Init.

type Throttle

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

Throttle implements the "log-once-then-count" discipline required for data-plane and repeated-error events (see the Log economy section of the unified-logging plan). The first occurrence of a key in a window returns emit=true with the count so far; subsequent occurrences within the window are suppressed and accumulated. When the window elapses, the next occurrence emits again and reports how many were suppressed.

It allocates only on first sight of a key and never on the suppressed path beyond a map lookup + atomic-free counter increment under a short lock, so it is safe on warm paths (it is NOT intended for the zero-alloc per-packet hot path — those events stay at Debug and are gated by level).

func NewThrottle

func NewThrottle(window time.Duration) *Throttle

NewThrottle returns a Throttle that emits at most once per key per window.

func (*Throttle) Allow

func (t *Throttle) Allow(key string) (emit bool, suppressed uint64)

Allow reports whether an event for key should be logged now. When emit is true, suppressed is the number of occurrences hidden since the last emit for this key (0 on the first ever emit).