Documentation
¶
Overview ¶
Package agentstats turns the kata guest agent's per-container cgroup accounting into the resource-usage sample ateom reports.
The micro-VM ateom uses it to answer ateompb.Ateom/GetWorkloadStats. The host cgroup is the wrong place to look on this runtime: the guest's RAM is a fixed allocation cloud-hypervisor takes at boot, so the host cgroup reads roughly the same whether the actor is idle or saturated. The numbers that move with the workload are the ones the guest kernel keeps, and the agent is what can read them.
This package is deliberately pure — it converts an already-fetched agentpb.CgroupStats and never talks to a guest — which keeps it testable without a live micro-VM and, unlike the rest of the micro-VM ateom, without the linux build tag.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Sample ¶
type Sample struct {
// MemoryCurrentBytes is what is currently charged to the container's guest
// cgroup, page cache included.
MemoryCurrentBytes uint64
// MemoryPeakBytes is the high-water mark of MemoryCurrentBytes. Zero when
// the guest kernel does not expose one: the agent fills it from the cgroup's
// max-usage file, which cgroup v2 only grew in Linux 5.19.
//
// For a single container this is exact; summed across containers it is an
// upper bound, not an observed maximum — see Plus for why.
MemoryPeakBytes uint64
// MemoryWorkingSetBytes is MemoryCurrentBytes less the reclaimable page
// cache, floored at zero — the figure to compare against a memory limit,
// since MemoryCurrentBytes drifts upward with cache the kernel would drop
// for free under pressure.
MemoryWorkingSetBytes uint64
// CPUUsageUsec is cumulative CPU time consumed by the container, as seen by
// the guest kernel.
CPUUsageUsec uint64
}
Sample is a point-in-time reading for one container, or the sum of several. It carries the same four numbers as the gVisor ateom's cgroupstats.Sample, because both feed the same four fields of GetWorkloadStatsResponse.
Anything the guest did not report reads as zero rather than failing the whole sample, for the same reason as there: a partial reading is more useful than none. FromCgroupStats says which fields can do that and why.
func FromCgroupStats ¶
func FromCgroupStats(cs *agentpb.CgroupStats) Sample
FromCgroupStats converts one container's guest cgroup accounting.
It never fails. Every field the agent left out reads as zero, and cs itself may be nil — the agent answers without cgroup stats for a container it has no accounting for, which is a normal state for one that has exited rather than an error. The caller decides what an all-zero container means; see the summing in the micro-VM ateom's GetWorkloadStats.
func (Sample) Plus ¶
Plus returns the sum of two samples, for accumulating an actor's containers into the one figure the proto reports.
Summing the peaks is an upper bound on the peak of the sum, not the peak of the sum itself: two containers that peaked at different moments add up to a total the actor never actually reached. The bound is the honest approximation, and for the single-container actors this runtime mostly serves it is exact.
The guest kernel does track the true figure: every container cgroup sits under the shared /ateomchv parent (see StartRootfsContainer and the CgroupsPath defaults in internal/kata), so with hierarchical accounting the parent's memory.peak is the actor-level maximum this sum approximates. The kata-agent just has no RPC that reads a cgroup by path — StatsContainer is per-container only. If the agent ever grows a sandbox-level stats read, that replaces this summing outright.
Saturating on overflow, so a nonsensical reading from one container cannot wrap the total to a small number and read as healthy.
Source Files