hoststats

package
v1.10.8 Latest Latest
Warning

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

Go to latest
Published: Sep 26, 2026 License: AGPL-3.0, Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package hoststats reads real host CPU and memory usage from a procfs directory. /proc/stat and /proc/meminfo already reflect the host even from inside a container, so the process's own /proc works out of the box; binding the host's procfs to /host/proc is an explicit alternative.

It is shared by the control plane and the node agent, so the figures both sides produce and the payload the agent pushes cannot drift apart.

Index

Constants

This section is empty.

Variables

View Source
var ErrNoBaseline = errors.New("hoststats: no cpu baseline yet")

ErrNoBaseline is returned by Sampler.Sample until it has a previous CPU reading to measure against.

Functions

func Available

func Available(procPath string) bool

Available reports whether procPath exposes a readable /proc/stat, i.e. host stats can be read from it.

func CPUPercent

func CPUPercent(a, b CPUTimes) float64

CPUPercent is the busy share of the interval between two samples, clamped to [0, 100]. A counter that went backwards reads as 0.

func MemFromVals

func MemFromVals(vals map[string]uint64) (total, avail uint64, err error)

MemFromVals resolves total and available memory from parsed meminfo keys (bytes). MemAvailable is preferred; the MemFree+Buffers+Cached sum is the fallback for kernels without it.

func ParseMemLine

func ParseMemLine(line string) (key string, kb uint64, ok bool)

ParseMemLine splits one meminfo row into its key and kB value.

func ReadLoad1

func ReadLoad1(procPath string) (float64, error)

ReadLoad1 reads the one-minute load average from procPath/loadavg.

func ReadMem

func ReadMem(procPath string) (total, avail uint64, err error)

ReadMem parses MemTotal and MemAvailable (bytes) from meminfo. Falls back to MemFree+Buffers+Cached for kernels without MemAvailable.

func ReadUptime

func ReadUptime(procPath string) (uint64, error)

ReadUptime reads the host's uptime in whole seconds from procPath/uptime.

Types

type CPUTimes

type CPUTimes struct {
	Total uint64
	Idle  uint64 // idle + iowait
}

CPUTimes is the aggregate "cpu" row of /proc/stat, in jiffies.

func ParseCPULine

func ParseCPULine(line string) (CPUTimes, error)

ParseCPULine reads the aggregate "cpu" row of /proc/stat. Shared with the remote sampler, which gets the same line from a helper container's stdout rather than from a file.

func ReadCPU

func ReadCPU(procPath string) (CPUTimes, error)

ReadCPU reads the aggregate CPU counters from procPath/stat.

type Report

type Report struct {
	CPUPercent    float64 `json:"cpu_percent"`
	MemTotalBytes uint64  `json:"mem_total_bytes"`
	MemUsedBytes  uint64  `json:"mem_used_bytes"`
	Load1         float64 `json:"load1"`
	UptimeSeconds uint64  `json:"uptime_s"`
}

Report is what a node agent pushes to POST /api/v1/agent/stats. It carries no identity and no timestamp: the control plane takes the node from the bearer token and stamps receipt time itself.

func (Report) Stats

func (r Report) Stats() Stats

Stats converts the report into a snapshot.

type Sampler

type Sampler struct {
	ProcPath string
	// contains filtered or unexported fields
}

Sampler measures CPU over the whole interval between successive calls rather than a short fixed window, so a bursty workload is averaged over what actually happened since the last report.

func (*Sampler) Sample

func (s *Sampler) Sample() (Report, error)

Sample returns a report covering the time since the previous call. The first call, and any call after the counters went backwards, only records a baseline and returns ErrNoBaseline.

type Stats

type Stats struct {
	CPUPercent    float64 `json:"cpu_percent"`
	MemTotalBytes uint64  `json:"mem_total_bytes"`
	MemUsedBytes  uint64  `json:"mem_used_bytes"`
	MemPercent    float64 `json:"mem_percent"`
}

Stats is a point-in-time host resource snapshot.

func Read

func Read(ctx context.Context, procPath string) (Stats, error)

Read samples host CPU (over a short interval) and memory from procPath (e.g. "/proc" or a bound "/host/proc"). Returns an error if the procfs files can't be read or parsed.

func StatsFrom

func StatsFrom(c1, c2 CPUTimes, memTotal, memAvail uint64) Stats

StatsFrom assembles a snapshot from two CPU samples and a memory reading.

Jump to

Keyboard shortcuts

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