diag

package
v0.8.0 Latest Latest
Warning

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

Go to latest
Published: Aug 27, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package diag provides a lightweight, always-on runtime watchdog that samples process resource metrics (goroutine count and post-GC live heap) on an interval and records a diagnostic when a threshold is crossed. It exists to catch runaway resource growth early and leave a durable, actionable artifact even when structured logging via GRUT_LOG is not enabled.

The watchdog is cheap: one runtime/metrics read and runtime.NumGoroutine per interval (default 60s), so it is safe to run for the entire session.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Alert

type Alert struct {
	Timestamp      time.Time
	Kind           string // kindGoroutines or kindHeap
	Message        string
	Goroutines     int
	Baseline       int
	HeapLiveBytes  uint64
	HeapGrowthRate float64
	NumGC          uint64
}

Alert describes a threshold breach detected by the watchdog.

type Profiler added in v0.8.0

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

Profiler owns all profiling resources for one command execution.

func StartProfiling added in v0.8.0

func StartProfiling(options ProfilingOptions, stderr io.Writer) *Profiler

StartProfiling applies requested sampling rates and starts file and HTTP profiling. Startup failures are warnings because profiling is diagnostic and must not prevent the requested command from running.

func (*Profiler) Close added in v0.8.0

func (p *Profiler) Close()

Close stops and waits for all profiling activity, restores runtime sampling rates, and flushes requested file profiles. It is safe to call concurrently.

type ProfilingOptions added in v0.8.0

type ProfilingOptions struct {
	CPUProfilePath       string
	MemoryProfilePath    string
	PprofAddress         string
	MutexProfileFraction SamplingRate
	BlockProfileRate     SamplingRate
}

ProfilingOptions configures process profiling for one command execution.

type SamplingRate added in v0.8.0

type SamplingRate struct {
	Enabled bool
	Rate    int
}

SamplingRate distinguishes an omitted sampling flag from an explicitly requested zero rate.

type Thresholds

type Thresholds struct {
	// GoroutineFloor is an absolute goroutine count that always triggers an
	// alert regardless of the startup baseline.
	GoroutineFloor int
	// GoroutineGrowth triggers an alert when the live goroutine count exceeds
	// GoroutineGrowth * baseline (and is at least GoroutineGrowthMin).
	GoroutineGrowth float64
	// GoroutineGrowthMin guards the growth check so a tiny baseline cannot
	// produce alerts at harmless goroutine counts.
	GoroutineGrowthMin int
	// HeapCeilingBytes triggers an alert when post-GC live heap reaches this
	// absolute ceiling.
	HeapCeilingBytes uint64
	// HeapGrowthWindow is the rolling interval used to calculate retained-heap
	// growth. Only samples from distinct GC cycles participate.
	HeapGrowthWindow time.Duration
	// HeapGrowthMinSamples is the number of strictly increasing post-GC samples
	// required before a growth alert can fire.
	HeapGrowthMinSamples int
	// HeapGrowthMinBytes ignores slopes whose total growth is smaller than this.
	HeapGrowthMinBytes uint64
	// HeapGrowthBytesPerMinute is the minimum sustained retained-heap slope.
	HeapGrowthBytesPerMinute uint64
	// Cooldown is the minimum time between alerts of the same kind.
	Cooldown time.Duration
}

Thresholds configures when the watchdog reports.

func DefaultThresholds

func DefaultThresholds() Thresholds

DefaultThresholds returns the built-in threshold configuration.

type Watchdog

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

Watchdog samples runtime metrics and reports threshold breaches.

func New

func New() *Watchdog

New creates a Watchdog with default cadence, thresholds, and reporter. The default reporter logs via slog and appends a durable diagnostic record under the app data directory, including a stack dump for goroutine alerts and a binary heap profile for heap alerts.

func (*Watchdog) Run

func (w *Watchdog) Run(ctx context.Context)

Run samples on the configured interval until ctx is cancelled. It takes an immediate baseline sample so the growth check has a reference point, then reports any breaches through the configured reporter.

func (*Watchdog) Start added in v0.8.0

func (w *Watchdog) Start(parent context.Context) func()

Start runs the watchdog in the background and returns an idempotent stop function. Stop cancels the watchdog and waits for its goroutine to exit.

Jump to

Keyboard shortcuts

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