memreport

package
v1.4.2 Latest Latest
Warning

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

Go to latest
Published: Aug 25, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package memreport summarises process memory by subtree.

It exists so an operator can see who is actually using memory BEFORE enabling any limit — it reads /proc and needs no cgroup, no systemd, and no configuration change. Less precise than cgroup accounting (shared pages are counted once per process that maps them), but precise enough to choose a ceiling, and available where cgroups are not.

Distinct from pkg/proctree, which kills process trees. This one only measures them.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BaseName added in v0.39.7

func BaseName(name string) string

BaseName strips a Windows executable suffix so one list of provider names matches on every platform.

Windows reports "claude.exe" where Linux reports "claude", and callers name providers the way a person types them. Without this the Running agents table was empty on Windows while four agents were plainly running — the caller's list matched nothing and the page said "no agent processes running", which reads as a broken feature rather than as a naming mismatch.

Case-insensitive on the suffix only: Windows filesystems are case-insensitive, so the same binary can appear as .exe or .EXE.

func ByCPUTicks added in v0.39.2

func ByCPUTicks(p Proc) uint64

func ByIO added in v0.39.2

func ByIO(p Proc) uint64

func ByRSS added in v0.39.2

func ByRSS(p Proc) uint64

ByRSS / ByCPUTicks / ByIO are the ranking keys for TopBy.

func CPUPercent

func CPUPercent(ticksDelta uint64, elapsedSec float64) float64

CPUPercent converts a tick delta over an elapsed period into percent of one core. 100 means one core fully busy; 250 means two and a half.

Returns 0 for a non-positive elapsed time rather than dividing by zero: two samples from the same instant carry no rate information.

func GroupByCPU added in v0.39.2

func GroupByCPU(g ProcGroup) float64

func GroupByIO added in v0.39.2

func GroupByIO(g ProcGroup) float64

func GroupByMem added in v0.39.2

func GroupByMem(g ProcGroup) float64

Ranking keys for TopGroupsBy.

func RateByCPU added in v0.39.2

func RateByCPU(p ProcRate) float64

Rate keys for TopRateBy.

func RateByIO added in v0.39.2

func RateByIO(p ProcRate) float64

func RateByMem added in v0.39.2

func RateByMem(p ProcRate) float64

func SumSubtree

func SumSubtree(procs []Proc, root int) uint64

SumSubtree totals RSS for root and every descendant.

Descendants are the point: a browser started by a tool started by an agent is where the memory actually is, and reading only the agent's own RSS reports a number wrong by an order of magnitude.

Visited-tracking is not defensive dressing: /proc is sampled without a lock, so a process can exit and its PID be reused mid-walk, producing parent links that form a cycle. Without it the walk would not terminate.

Types

type History

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

History is a bounded time series, safe for concurrent use.

func NewHistory

func NewHistory(retention time.Duration, maxPoints int) *History

NewHistory builds a series bounded by both a time window and a hard point ceiling. Non-positive values fall back to defaults rather than meaning "unlimited": an unbounded diagnostic buffer is a memory leak in a feature whose purpose is preventing memory exhaustion.

func (*History) Agents

func (h *History) Agents(since time.Time) []Sample

Agents returns the per-agent series, oldest first. Optionally limited to samples at or after since.

func (*History) Machine

func (h *History) Machine(since time.Time) []MachineSample

Machine returns the machine-wide series, oldest first.

func (*History) Peaks

func (h *History) Peaks() map[string]Sample

Peaks reports the highest RSS and CPU seen per provider across the retained window — the numbers a limit must actually accommodate, and exactly what a single snapshot misses.

func (*History) Record

func (h *History) Record(now time.Time, procs []Proc, roots []Proc, totalBytes, availBytes uint64)

Record turns one /proc snapshot into rate-bearing samples.

now is passed in rather than read from the clock so tests can drive the rate arithmetic deterministically.

func (*History) SetRetention

func (h *History) SetRetention(d time.Duration)

SetRetention updates the window at runtime and purges immediately, so lowering it in the UI frees memory now rather than at the next sample.

func (*History) Stats

func (h *History) Stats() Stats

Stats reports the buffer's current contents and bounds.

type MachineSample

type MachineSample struct {
	At             time.Time `json:"at"`
	TotalBytes     uint64    `json:"total_bytes"`
	AvailableBytes uint64    `json:"available_bytes"`
	AgentBytes     uint64    `json:"agent_bytes"`
	AgentCPUPct    float64   `json:"agent_cpu_pct"`
	AgentProcs     int       `json:"agent_procs"`

	// Machine-wide totals, recorded alongside the agent figures so the
	// chart has something to show when no agent is running — which is
	// most of the time on a box that is merely slow. Also gives the agent
	// numbers a denominator: 400 MB of agents means one thing when the
	// machine is at 2 GB and another when it is at 30.
	MachineUsedBytes uint64  `json:"machine_used_bytes"`
	MachineCPUPct    float64 `json:"machine_cpu_pct"`
	MachineProcs     int     `json:"machine_procs"`
}

MachineSample is one observation of the machine as a whole, recorded alongside the per-agent rows so a spike can be read in context: 1.5 GB of agents means something different on a 3 GB box than on a 32 GB one.

type Proc

type Proc struct {
	PID      int
	PPID     int
	Name     string
	RSSBytes uint64
	// CPUTicks is utime+stime in clock ticks since process start.
	CPUTicks uint64
	// IOReadBytes / IOWriteBytes are read_bytes/write_bytes from
	// /proc/<pid>/io — actual block-device traffic, not page-cache hits.
	// Both are 0 when the file is unreadable, which is normal for
	// processes owned by another user.
	IOReadBytes  uint64
	IOWriteBytes uint64
	// Cmdline is the full command the process was started with, argv
	// joined by spaces.
	//
	// The name alone is frequently useless for identification: "node",
	// "python3", and "MainThread" say nothing about which of several
	// identical-looking processes is the one eating the machine. The
	// command line is what distinguishes them.
	//
	// Empty when unreadable — kernel threads have none, and another
	// user's process may refuse it. Callers fall back to Name.
	Cmdline string
}

Proc is one process as sampled from /proc.

CPUTicks and IO counters are CUMULATIVE since the process started, not rates. A rate needs two samples and the elapsed time between them — see CPUPercent — because /proc has no instantaneous "current CPU%".

func LargestDescendant

func LargestDescendant(procs []Proc, root int) Proc

LargestDescendant returns the heaviest process strictly below root, or a zero Proc when root has no descendants.

Reported alongside the subtree total because the total alone does not say what to do: "claude 1.4 GB" invites raising a limit, while "claude 1.4 GB, of which chromium is 1.2 GB" points at the actual cause.

func Roots

func Roots(procs []Proc, names []string) []Proc

Roots returns processes whose name matches any of names.

func Snapshot

func Snapshot() ([]Proc, error)

Snapshot samples every readable process.

Processes that vanish mid-walk are skipped rather than failing the sample: a snapshot of a moving system is expected to be slightly stale, not impossible.

func Subtree added in v0.39.2

func Subtree(procs []Proc, root int, limit int) []Proc

Subtree returns every process in root's tree, heaviest first, capped at limit (0 = uncapped).

This is the task-manager view: the aggregate in Totals answers "how much is this agent using", while the list answers "which process is using it" — the question an operator actually acts on. Sorted by RSS because that is what a limit is set against; ties break on PID so repeated calls against one snapshot render in a stable order rather than shuffling between refreshes.

The cap matters: an agent driving a browser can have dozens of renderer processes, and an uncapped list would grow the API payload without telling the operator anything the top entries did not.

func TopBy added in v0.39.2

func TopBy(procs []Proc, key func(Proc) uint64, limit int) []Proc

TopBy ranks every process on the machine and returns the first limit.

Machine-wide on purpose, and distinct from Subtree: an operator asking "why is this box slow" needs the answer even when no agent is running, and the culprit is frequently not an agent at all. Subtree attributes usage to a session; this attributes it to the machine.

key selects the dimension. Ties break on PID so repeated calls against one snapshot render in a stable order rather than shuffling between refreshes.

type ProcGroup added in v0.39.2

type ProcGroup struct {
	Name  string
	Count int
	// PIDs of the members, heaviest first, so a caller can expand a group
	// into its parts without a second pass over the snapshot.
	Members []ProcRate

	RSSBytes   uint64
	CPUPct     float64
	IOReadBps  uint64
	IOWriteBps uint64

	// PctOfTotal is this group's share of a caller-supplied total. Filled
	// by GroupBy when a total is given, because the share is what makes a
	// number interpretable: "2.1 GB" means nothing until you know whether
	// the machine has 4 GB or 64.
	PctOfMachineMem float64
}

ProcGroup is every process sharing one executable name, summed.

func GroupBy added in v0.39.2

func GroupBy(procs []ProcRate, machineMemBytes uint64) []ProcGroup

GroupBy collapses rated processes by name.

machineMemBytes may be 0 when the machine's memory is unknown; the share is then left at zero rather than computed against a fabricated denominator.

func TopGroupsBy added in v0.39.2

func TopGroupsBy(groups []ProcGroup, key func(ProcGroup) float64, limit int) []ProcGroup

TopGroupsBy ranks groups and returns the first limit, dropping the zero-valued tail. Ties break on name so the order is stable between refreshes.

type ProcRate added in v0.39.2

type ProcRate struct {
	Proc
	CPUPct     float64
	IOReadBps  uint64
	IOWriteBps uint64
}

ProcRate is one process with its instantaneous rates.

func TopRateBy added in v0.39.2

func TopRateBy(procs []ProcRate, key func(ProcRate) float64, limit int) []ProcRate

TopRateBy ranks rated processes and returns the first limit, dropping the zero-valued tail so a quiet machine shows a short list rather than a table padded with idle system processes.

type RateTracker added in v0.39.2

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

RateTracker diffs consecutive machine-wide snapshots.

Not safe for concurrent use; the API handler owns one and calls it from a single request path.

func NewRateTracker added in v0.39.2

func NewRateTracker() *RateTracker

NewRateTracker returns an empty tracker. Its first Update reports zero rates — a rate needs two observations, and inventing one from a process's lifetime total would spike wildly for anything long-lived.

func (*RateTracker) Update added in v0.39.2

func (t *RateTracker) Update(now time.Time, procs []Proc) []ProcRate

Update records a snapshot and returns each process with rates derived against the previous one.

type Sample

type Sample struct {
	At         time.Time `json:"at"`
	Provider   string    `json:"provider"`
	PID        int       `json:"pid"`
	RSSBytes   uint64    `json:"rss_bytes"`
	CPUPct     float64   `json:"cpu_pct"`
	IOReadBps  uint64    `json:"io_read_bps"`
	IOWriteBps uint64    `json:"io_write_bps"`
	Procs      int       `json:"procs"`
}

Sample is one observation of one agent's process tree.

type Sampler

type Sampler struct {
	History *History
	// Interval between samples. Non-positive falls back to 15s rather
	// than spinning: a zero-interval loop would peg a core doing nothing
	// but reading /proc.
	Interval time.Duration
	// Names are the process names treated as tree roots.
	Names []string
	// TotalAvail reports machine memory. Injected so the sampler stays
	// testable without the real machine, and so this package does not
	// depend on sysmem (which would be a cycle once sysmem grows).
	TotalAvail func() (total, available uint64)
	// Enabled gates sampling per tick, read live so an operator turning
	// the guard off stops the walk without restarting wick.
	Enabled func() bool
}

Sampler periodically records a snapshot into a History.

func (*Sampler) Run

func (s *Sampler) Run(ctx context.Context)

Run samples until ctx is cancelled. Intended to be started in its own goroutine at boot.

type Stats

type Stats struct {
	AgentPoints   int        `json:"agent_points"`
	MachinePoints int        `json:"machine_points"`
	RetentionSec  int        `json:"retention_sec"`
	MaxPoints     int        `json:"max_points"`
	OldestAt      *time.Time `json:"oldest_at,omitempty"`
	SpanSec       int        `json:"span_sec"`
}

Stats describes what the buffer currently holds, so the UI can show "12 minutes of history, 240 points" instead of an unlabelled chart.

type Totals

type Totals struct {
	RSSBytes     uint64
	CPUTicks     uint64
	IOReadBytes  uint64
	IOWriteBytes uint64
	// Procs counts processes in the subtree. A fork bomb shows up here
	// long before it shows up in RSSBytes — thousands of tiny processes
	// stay under every memory ceiling while crippling the scheduler.
	Procs int
}

Totals is every resource for one subtree, summed.

func SumSubtreeAll

func SumSubtreeAll(procs []Proc, root int) Totals

SumSubtreeAll totals every resource for root and its descendants in one walk, so a sampler does not traverse the same tree four times.

Same cycle-safety as SumSubtree: /proc is sampled without a lock, so a reused PID can produce parent links that form a loop.

Jump to

Keyboard shortcuts

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