obs

Documentation

Overview

Package obs is the operator-observability seam. It builds a single structured logger (stdlib log/slog) whose level is controlled by the -v flag and the HERRSCHER_LOG env, so every diagnostic line carries a level and stable fields (session, category, component) instead of an interpolated string. This is operator logging on stderr only — user-facing gateway rendering is untouched.

Index

• Constants
• func NewLogger(w io.Writer, level slog.Level) *slog.Logger
• func ParseLevel(verbose bool, env string) slog.Level
• func Stderr(verbose bool) *slog.Logger
• type Backoff
  • func RestartBackoff() *Backoff
  • func (b *Backoff) Next(ranFor time.Duration) time.Duration

Constants

const EnvLevel = "HERRSCHER_LOG"

EnvLevel is the env var that selects the operator log level when -v is unset.

Functions

func NewLogger

func NewLogger(w io.Writer, level slog.Level) *slog.Logger

NewLogger builds a text-handler logger writing to w at the given level.

func ParseLevel

func ParseLevel(verbose bool, env string) slog.Level

ParseLevel resolves the operator log level. A set -v flag forces debug; otherwise the value (debug|info|warn|error, case/space-insensitive) decides, defaulting to info for empty or unrecognized input.

func Stderr

func Stderr(verbose bool) *slog.Logger

Stderr builds the default operator logger: a text handler to stderr at the level resolved from the -v flag and HERRSCHER_LOG.

Types

type Backoff

type Backoff struct {
	Base   time.Duration // first delay (n=0)
	Max    time.Duration // upper cap before jitter; 0 ⇒ uncapped
	Factor float64       // geometric growth per consecutive failure
	Jitter float64       // jitter fraction in [0,1]: delay ∈ [target·(1-Jitter), target]
	Reset  time.Duration // a run ≥ Reset returns the next delay to Base; 0 ⇒ never

	// Rand draws the jitter sample in [0,1); nil falls back to math/rand.
	Rand func() float64
	// contains filtered or unexported fields
}

Backoff computes restart delays that grow geometrically (base·factorⁿ, capped at Max) with full jitter, and reset to base after a run that lasted at least Reset — so a process that ran healthily restarts fast while a tight crash loop backs off. The zero value is unusable; set at least Base and Factor.

func RestartBackoff

func RestartBackoff() *Backoff

RestartBackoff is the shared restart-loop policy: 1s base, ×2 growth capped at 30s, ±20% jitter, resetting to base after a 60s healthy run. The supervisor and the remote plugin-host loop both restart on this schedule.

func (*Backoff) Next

func (b *Backoff) Next(ranFor time.Duration) time.Duration

Next returns the delay before the next restart, given how long the attempt that just failed ran (ranFor). A ranFor ≥ Reset clears the failure streak so the delay returns to Base.