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.
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
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.