Help us shape the future of Go! Take the 2026 Go Developer Survey

machine

package
v0.62.0-rc.3 Latest Latest
Warning

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

 Go to latest Published: Oct 1, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

Documentation

Overview

Package machine reads the numbers that decide whether the workstation survives the next hour: RAM and swap, memory pressure, the Claude Desktop cgroup, tmpfs and disk, build slots, kind clusters and the kernel's OOM kills. Linux only: /proc, cgroup v2 and the journal.

Index

Constants

View Source 
const (
	Ollama   = "ollama"
	Lemonade = "lemonade"
)

The host's model servers, which load models into the iGPU's memory.

View Source 
const DefaultOOMDSwapLimit = 90

DefaultOOMDSwapLimit is systemd-oomd's SwapUsedLimit when no oomd.conf sets it: the percent of swap in use at which it kills the monitored cgroup's largest swap user, however much RAM is free.

Variables

This section is empty.

Functions

func FindMemcapScope added in v0.14.0 

func FindMemcapScope(unit string) string

FindMemcapScope returns the cgroup of the capped run's scope unit (as a run event names it, "memcap-….scope"), or "" when it has ended.

func FindScope 

func FindScope() string

FindScope returns the largest Claude Desktop scope, or "" when none runs.

func GTTUsedMiB added in v0.38.0 

func GTTUsedMiB(gpus []GPU) int

GTTUsedMiB is the GTT all devices pin.

func OOMDSwapLimit added in v0.37.4 

func OOMDSwapLimit() int

OOMDSwapLimit returns systemd-oomd's SwapUsedLimit in percent: the last setting in oomd.conf and its drop-ins, DefaultOOMDSwapLimit without one.

func ParseOllamaLoads added in v0.38.0 

func ParseOllamaLoads(journal string) map[string]string

ParseOllamaLoads maps each model blob to the address of the client whose request loaded it last: the first model request logged after the load that started before it (gin logs a request when it ends, with its latency). A blob whose last load's request is still running maps to "": an earlier load's client is not its.

func ParseOomd added in v0.45.2 

func ParseOomd(journal string) []string

ParseOomd keeps the lines of systemd-oomd's journal where it killed a cgroup: the event that takes every session down at once.

func ReadCPUPSISome10 added in v0.38.1 

func ReadCPUPSISome10() (float64, error)

ReadCPUPSISome10 returns CPU pressure "some avg10" in percent: the share of the last ten seconds in which at least one runnable task waited for a CPU.

func ReadForks added in v0.42.0 

func ReadForks() (uint64, error)

ReadForks returns the processes forked since boot: the "processes" line of /proc/stat.

func ReadLoad 

func ReadLoad() ([3]float64, error)

ReadLoad returns the 1, 5 and 15 minute load averages.

func ReadPSIFull60 

func ReadPSIFull60() (float64, error)

ReadPSIFull60 returns memory pressure "full avg60" in percent: the share of the last minute in which every task stalled on memory.

func SwapoffRuns added in v0.37.6 

func SwapoffRuns() bool

SwapoffRuns reports whether a swapoff process runs. While swapoff drains a device the kernel has already taken the device out of SwapTotal, but its pages still count as used, so swap reads near 100 % full while it is being emptied.

func UnloadLemonade added in v0.45.0 

func UnloadLemonade(ctx context.Context, url, model string) error

UnloadLemonade asks the Lemonade Server at url to drop model from memory now (POST /api/v1/unload); its weights stay on disk.

func UnloadOllama added in v0.40.0 

func UnloadOllama(ctx context.Context, url, model string) error

UnloadOllama asks the ollama at url to drop model from memory now; its weights stay on disk and the next request loads it again.

func Zone added in v0.27.0 

func Zone() (*time.Location, error)

Zone is the machine's time zone as timedatectl sets it, read now: a long-running process's time.Local stays the zone it started in.

Types

type Cluster 

type Cluster struct {
	Name   string `json:"name"`
	Nodes  int    `json:"nodes"`
	MemMiB int    `json:"memMiB"`
	// Containers are the node containers' full ids.
	Containers []string `json:"containers"`
	// RunningFor is docker's age of its oldest node ("2 hours ago").
	RunningFor string `json:"runningFor"`
}

Cluster is a running kind cluster.

func KindClusters 

func KindClusters(ctx context.Context) ([]Cluster, error)

KindClusters lists the kind clusters from the node containers docker runs.

type Disk 

type Disk struct {
	Path    string `json:"path"`
	UsedMiB int    `json:"usedMiB"`
	FreeMiB int    `json:"freeMiB"`
	// TotalMiB is the filesystem's size.
	TotalMiB int `json:"totalMiB"`
}

Disk is a filesystem's usage in MiB.

func ReadDisk 

func ReadDisk(path string) (Disk, error)

ReadDisk returns the usage of the filesystem path lives on; free is what an unprivileged process can still write.

type GPU added in v0.38.0 

type GPU struct {
	Device      string `json:"device"`
	GTTUsedMiB  int    `json:"gttUsedMiB"`
	GTTTotalMiB int    `json:"gttTotalMiB"`
	VRAMUsedMiB int    `json:"vramUsedMiB"`
	VRAMTotMiB  int    `json:"vramTotalMiB"`
}

GPU is an amdgpu device's memory in MiB. On an APU, GTT is system RAM the driver pins for the GPU: no cgroup counts it, but it is gone from MemAvailable all the same.

func ReadGPUs added in v0.38.0 

func ReadGPUs() []GPU

ReadGPUs returns every amdgpu device's GTT and VRAM, none on a machine without one.

type HostModel added in v0.45.0 

type HostModel struct {
	// Server is the model server holding it: Ollama or Lemonade.
	Server  string `json:"server"`
	Name    string `json:"name"`
	SizeMiB int    `json:"sizeMiB"`
	// GPUMiB is the part on the GPU: on an APU, GTT.
	GPUMiB    int       `json:"gpuMiB,omitempty"`
	ExpiresAt time.Time `json:"expiresAt,omitzero"`
	// Client is who sent the request that loaded it, as the server's log
	// shows it or, while that request still runs, as the one client
	// connected to the server: an address, with the kind node's name when
	// one has it.
	Client string `json:"client,omitempty"`
}

HostModel is a model one of the host's model servers holds in memory.

func LemonadeModels added in v0.45.0 

func LemonadeModels(ctx context.Context, url string) ([]HostModel, error)

LemonadeModels asks the Lemonade Server at url which models it holds (GET /api/v1/health) and how large each one's weights are (GET /api/v1/models, in GB). Lemonade logs no client address: a model's client is the one peer connected to url's port, and none when several are. An empty url means none is watched.

func OllamaModels added in v0.38.0 

func OllamaModels(ctx context.Context, url, unit string, serviceLog func(ctx context.Context, unit, grep string) ([]byte, error)) ([]HostModel, error)

OllamaModels asks the ollama at url which models it holds (GET /api/ps) and finds each one's loading client in the log of unit (serviceLog). A load whose request still runs is not in the journal yet: its client is the one peer connected to url's port, and none when several are. An empty url means none is watched.

func (HostModel) Label added in v0.45.0 

func (m HostModel) Label() string

Label is the model's name after its server's, as the watch prints it.

func (HostModel) Node added in v0.45.0 

func (m HostModel) Node() string

Node is the kind node's name in Client, "" when the client is none.

func (HostModel) Unload added in v0.45.0 

func (m HostModel) Unload(ctx context.Context, url string) error

Unload asks the model server holding m to drop it from memory now; its weights stay on disk and the next request loads it again. url is that server's API.

type Mem 

type Mem struct {
	TotalMiB     int `json:"totalMiB"`
	AvailableMiB int `json:"availableMiB"`
	SwapTotalMiB int `json:"swapTotalMiB"`
	SwapUsedMiB  int `json:"swapUsedMiB"`
	ShmemMiB     int `json:"shmemMiB"`
}

Mem is /proc/meminfo in MiB.

func ReadMem 

func ReadMem() (Mem, error)

ReadMem parses /proc/meminfo.

func (Mem) OOMDHeadroomMiB added in v0.37.4 

func (m Mem) OOMDHeadroomMiB(limit int) int

OOMDHeadroomMiB is the swap growth left before systemd-oomd's trigger at limit percent; negative once swap is past it.

type OOMKill 

type OOMKill struct {
	At         time.Time `json:"at"`
	PID        int       `json:"pid"`
	Task       string    `json:"task"`
	AnonMiB    int       `json:"anonMiB"`
	Constraint string    `json:"constraint,omitempty"`
	// Memcg is the cgroup whose limit was hit: a memcap scope, a kind
	// lab's pod, or the desktop scope.
	Memcg string `json:"memcg,omitempty"`
}

OOMKill is one process the kernel killed for memory.

func ParseOOM 

func ParseOOM(journal string) []OOMKill

ParseOOM pairs the kernel's oom-kill and "Killed process" lines by pid.

type Scope 

type Scope struct {
	Path       string `json:"path"`
	CurrentMiB int    `json:"currentMiB"`
	AnonMiB    int    `json:"anonMiB"`
	SwapMiB    int    `json:"swapMiB"`
	High       string `json:"high"`
	Max        string `json:"max"`
	SwapMax    string `json:"swapMax"`
	OOMKills   int64  `json:"oomKills"`
	HighEvents int64  `json:"highEvents"`
}

Scope is the Claude Desktop cgroup: every session's CLI and MCP servers live in it, and systemd-oomd kills it whole.

func ReadScope 

func ReadScope(path string) *Scope

ReadScope reads the cgroup at path.

type Slot 

type Slot struct {
	N      int    `json:"n"`
	Free   bool   `json:"free"`
	Holder string `json:"holder,omitempty"`
}

Slot is one of memcap's build slots.

func ReadSlots 

func ReadSlots(dir string, n int) []Slot

ReadSlots probes memcap's slot locks without blocking.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.