README
¶
memusage
memusage.Log(ctx) records kernel memory high-water marks through the context's
clog logger. Call it when an operation finishes to capture peaks even when the
operation completes between monitoring samples:
import "github.com/chainguard-dev/terraform-infra-common/pkg/memusage"
func run(ctx context.Context) error {
defer memusage.Log(ctx)
// Perform the operation.
return nil
}
The memory usage log entry contains:
| Field | Meaning |
|---|---|
process_peak_rss_bytes |
Linux /proc/self/status VmHWM, converted from KiB to bytes. Excludes child processes and unmapped scratch files. |
process_peak_rss_error |
Error reading or parsing process accounting, or null on success. |
container_peak_memory_bytes |
Cgroup v2 memory.peak, falling back to v1 memory.max_usage_in_bytes when v2 accounting is absent. Includes charged scratch files and child processes. |
container_peak_memory_source |
Accounting file path relative to /, or empty if no supported controller was found. |
container_peak_memory_error |
Error reading or verifying container accounting, or null on success. |
Each file read is bounded. The reader verifies current-process membership and the controller mount root; nested or unverified layouts remain unknown instead of reporting a parent's peak. Missing, malformed, or unsupported accounting is logged as null with an error, never as zero. Non-Linux platforms may report neither value.
These counters describe the process and cgroup lifetimes, respectively, rather than one operation. Calls do not reset the counters. A hard kill or OOM can prevent a deferred log, so continue checking execution status and monitoring metrics.
The package keeps no shared state and is safe for concurrent use.
memusage.ReadContainer() returns the container cgroup's current usage, limit,
and lifetime peak for callers that sample memory themselves. It uses the same
bounded, verified reads: each value is a *uint64 with its own error, and a
missing, malformed, or unlimited (max) value is nil with an error, never zero.
Documentation
¶
Overview ¶
Package memusage logs Linux process and container memory high-water marks. Accounting is read on each call; no background sampling or shared state is used. Log is safe for concurrent use.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Log ¶
Log records Linux kernel memory high-water marks with the context logger. Missing or unsupported accounting is logged as null with an error, not zero. The process RSS excludes children and unmapped tmpfs; the cgroup peak includes all memory charged to the container, including child processes and scratch files. These are lifetime peaks, not per-call measurements. Log is safe for concurrent use.
Types ¶
type Container ¶ added in v1.56.0
type Container struct {
// Current is the memory charged to the container now: cgroup v2
// memory.current or v1 memory.usage_in_bytes.
Current *uint64
CurrentErr error
// Limit is the memory limit: cgroup v2 memory.max or v1
// memory.limit_in_bytes. A v2 limit of "max" is unknown.
Limit *uint64
LimitErr error
// Peak is the lifetime high-water mark: cgroup v2 memory.peak or v1
// memory.max_usage_in_bytes. It only rises, so it shows how close the
// container came to its limit even between samples.
Peak *uint64
PeakErr error
}
Container is a snapshot of the container cgroup's memory accounting, read from the controller mounted at the current process's root. A nil value is unknown, and its error says why; it is never reported as zero.
func ReadContainer ¶ added in v1.56.0
func ReadContainer() Container
ReadContainer reads the container cgroup's current usage, limit, and lifetime peak. Each read is bounded and verified as Log's peak read is.
Source Files