Documentation
¶
Overview ¶
Package cgroupstats reads resource usage out of a cgroup v2 directory.
The gVisor ateom uses it to answer ateompb.Ateom/GetWorkloadStats: the sentry hosts the whole sandbox in one host process, so the sandbox's cgroup leaf is where the workload's memory and CPU actually show up.
Every read is scoped to a caller-supplied directory rather than a hardcoded /sys/fs/cgroup path, which keeps the parsing testable from a fixture tree without root or a live sandbox. The package deliberately does not know what a sandbox is; it reads what the kernel reports in a handful of files.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Sample ¶
type Sample struct {
// MemoryCurrentBytes is memory.current: bytes currently charged to the
// cgroup, including page cache.
MemoryCurrentBytes uint64
// MemoryPeakBytes is memory.peak: the high-water mark of MemoryCurrentBytes
// over the cgroup's lifetime. Zero on kernels below 5.19, which do not have
// the file.
MemoryPeakBytes uint64
// MemoryWorkingSetBytes is MemoryCurrentBytes less the reclaimable page
// cache (memory.stat's inactive_file), floored at zero. This is the estimate
// of "memory that would have to be paged in again if reclaimed" that cAdvisor
// and the kubelet report, and it is the field to compare against a memory
// limit; MemoryCurrentBytes drifts upward with cache that the kernel will
// drop for free under pressure.
MemoryWorkingSetBytes uint64
// CPUUsageUsec is cpu.stat's usage_usec: cumulative CPU time consumed by the
// cgroup since it was created. Zero if the cpu controller was not delegated
// to this cgroup (see ateomcgroup.Delegate, which enables controllers
// best-effort and carries on when one cannot be enabled).
CPUUsageUsec uint64
// OOMKills is memory.events' oom_kill: processes in the cgroup the kernel's
// OOM killer has killed over the cgroup's lifetime. Zero if the file is
// absent.
OOMKills uint64
// Empty is true when cgroup.events reports populated 0: no process is left
// in the cgroup. It reads false when the file is absent, so a kernel that
// does not say is never taken for a dead sandbox.
Empty bool
}
Sample is a point-in-time reading of one cgroup v2 directory.
Fields the kernel does not expose read as zero rather than failing the whole sample: a partial reading is more useful than none, and the alternative is an ateom that reports nothing at all on a kernel missing one file. Read's doc comment says which fields can do this and why.
func Read ¶
Read returns a Sample for the cgroup v2 directory at dir.
It fails only when the cgroup itself cannot be read: a missing directory, or a memory.current that is absent or unparseable. That case is reported with an error wrapping fs.ErrNotExist when the cause is a missing path, so callers can distinguish "this sandbox is gone" from "this file is malformed".
Everything else degrades to zero on that one field, because each has a legitimate reason to be missing on a healthy system: memory.peak does not exist before kernel 5.19, memory.stat's inactive_file is absent without the memory controller's full accounting, and cpu.stat is absent when the cpu controller was not delegated. Failing the sample for any of them would mean reporting no memory numbers because the node could not report CPU. memory.events and cgroup.events are optional in the same way.
Source Files