hostpressure

package
v1.3.1 Latest Latest
Warning

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

Go to latest
Published: Nov 16, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package hostpressure watches CPU and memory pressure on the host and tells the build path to wait or slow down before the kernel starts killing processes.

Index

Constants

View Source
const WaitMessage = "waiting: host under memory pressure"

WaitMessage is the status shown while a new build waits for the host to recover.

Variables

View Source
var ErrUnsupported = errors.New("hostpressure: no memory source on this host")

ErrUnsupported means the host exposes no memory source to read.

Functions

This section is empty.

Types

type Config

type Config struct {
	Enabled     bool
	ShedEnabled bool

	CPUWarn, CPUCritical         float64 // cpu some avg10
	MemWarn, MemCritical         float64 // memory some avg10
	MemFullWarn, MemFullCritical float64 // memory full avg10
	AvailWarn, AvailCritical     float64 // MemAvailable as percent of total, lower is worse
	LoadWarn, LoadCritical       float64 // used only without PSI

	// ExitPercent scales every enter threshold to its exit threshold so a state leaves only after it clearly eased.
	ExitPercent float64
	Hold        time.Duration
	Jitter      time.Duration
	Interval    time.Duration
	NoSwapRAM   int64 // bytes: flag missing swap below this much RAM
}

Config holds the live thresholds. Percent fields are 0 to 100, load is load1 per CPU times 100.

type Consumer

type Consumer struct {
	Name     string `json:"name"`
	MemBytes int64  `json:"mem_bytes"`
}

Consumer is one container's memory use.

type ConsumerFunc

type ConsumerFunc func(ctx context.Context) ([]Consumer, error)

ConsumerFunc lists the biggest memory users; it must be bounded.

type Guard

type Guard struct {

	// OnChange runs after the state changes, outside the lock.
	OnChange func(Status)
	// Sink receives every evaluation, for gauges.
	Sink func(Status)
	// contains filtered or unexported fields
}

Guard evaluates samples with hysteresis and gates new builds.

func New

func New(read ReadFunc, cfg func() Config, logger *slog.Logger) *Guard

New builds a Guard that starts in ok.

func (*Guard) Admit

func (g *Guard) Admit(ctx context.Context, wait func(msg string)) error

Admit blocks a new build while the host is critical, calls wait once with WaitMessage, then resumes after a random jitter. It fails only when ctx ends and never touches work that is already running.

func (*Guard) BuildCap

func (g *Guard) BuildCap(limit int) int

BuildCap lowers a build concurrency limit to 1 while the host is warm or worse; 0 (unlimited) is capped too.

func (*Guard) Observe

func (g *Guard) Observe(ctx context.Context) Status

Observe takes one reading and applies it. Escalation is immediate; stepping down needs Hold below the exit thresholds.

func (*Guard) Run

func (g *Guard) Run(ctx context.Context)

Run observes on the configured interval until ctx ends.

func (*Guard) SetConsumers

func (g *Guard) SetConsumers(f ConsumerFunc)

SetConsumers wires the top consumer lookup run on each escalation.

func (*Guard) Status

func (g *Guard) Status() Status

Status returns the last evaluation.

type ProcReader

type ProcReader struct {
	Root   string
	NumCPU func() int
}

ProcReader reads a /proc shaped tree rooted at Root ("/proc" when empty).

func (ProcReader) Read

func (p ProcReader) Read() (Sample, error)

Read implements ReadFunc.

type ReadFunc

type ReadFunc func() (Sample, error)

ReadFunc returns the current reading; tests inject a fake.

type Sample

type Sample struct {
	PSI       bool    `json:"psi"`
	CPUSome10 float64 `json:"cpu_some_avg10"`
	CPUSome60 float64 `json:"cpu_some_avg60"`
	MemSome10 float64 `json:"mem_some_avg10"`
	MemSome60 float64 `json:"mem_some_avg60"`
	MemFull10 float64 `json:"mem_full_avg10"`
	MemFull60 float64 `json:"mem_full_avg60"`

	MemTotal     int64   `json:"mem_total_bytes"`
	MemAvailable int64   `json:"mem_available_bytes"`
	SwapTotal    int64   `json:"swap_total_bytes"`
	SwapFree     int64   `json:"swap_free_bytes"`
	NumCPU       int     `json:"num_cpu"`
	Load1        float64 `json:"load1"`
}

Sample is one reading. PSI is false where /proc/pressure is missing (old kernels, containers, other systems).

type State

type State string

State is how stressed the host is, worst last.

const (
	StateOK       State = "ok"
	StateWarn     State = "warn"
	StateCritical State = "critical"
)

States.

func (State) Rank

func (s State) Rank() int

Rank is 0 for ok, 1 for warn and 2 for critical, for gauges.

type Status

type Status struct {
	State        State      `json:"state"`
	Since        time.Time  `json:"since"`
	Source       string     `json:"source"` // psi, fallback or unavailable
	Reasons      []string   `json:"reasons"`
	Sample       Sample     `json:"sample"`
	TopConsumers []Consumer `json:"top_consumers"`
	Actions      []string   `json:"actions"`
	NoSwap       bool       `json:"no_swap"`
}

Status is the last evaluation.

Jump to

Keyboard shortcuts

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