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 ¶
- func BaseName(name string) string
- func ByCPUTicks(p Proc) uint64
- func ByIO(p Proc) uint64
- func ByRSS(p Proc) uint64
- func CPUPercent(ticksDelta uint64, elapsedSec float64) float64
- func GroupByCPU(g ProcGroup) float64
- func GroupByIO(g ProcGroup) float64
- func GroupByMem(g ProcGroup) float64
- func RateByCPU(p ProcRate) float64
- func RateByIO(p ProcRate) float64
- func RateByMem(p ProcRate) float64
- func SumSubtree(procs []Proc, root int) uint64
- type History
- func (h *History) Agents(since time.Time) []Sample
- func (h *History) Machine(since time.Time) []MachineSample
- func (h *History) Peaks() map[string]Sample
- func (h *History) Record(now time.Time, procs []Proc, roots []Proc, totalBytes, availBytes uint64)
- func (h *History) SetRetention(d time.Duration)
- func (h *History) Stats() Stats
- type MachineSample
- type Proc
- type ProcGroup
- type ProcRate
- type RateTracker
- type Sample
- type Sampler
- type Stats
- type Totals
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func BaseName ¶ added in v0.39.7
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 CPUPercent ¶
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 GroupByMem ¶ added in v0.39.2
Ranking keys for TopGroupsBy.
func SumSubtree ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
SetRetention updates the window at runtime and purges immediately, so lowering it in the UI frees memory now rather than at the next sample.
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 ¶
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 Snapshot ¶
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
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
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.
type ProcRate ¶ added in v0.39.2
ProcRate is one process with its instantaneous rates.
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.
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.
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 ¶
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.