Documentation
¶
Overview ¶
Package process measures resource usage — wall-clock time, CPU time, and (on platforms that support it) peak memory, page faults, context switches, and block I/O — for two distinct scopes: the current (atmos) process's own usage (via Baseline/Since/SelfUsageSoFar), and a subprocess tree's usage (via CollectFromProcessState, e.g. terraform/tofu plus its child provider plugins). Combine merges the two scopes together for callers that need a single number covering "everything this command did."
Index ¶
- func Accumulate(m *ProcessMetrics)
- func DisplayFinalSummary(atmosConfig *schema.AtmosConfiguration)
- func DisplaySummary(label string, m ProcessMetrics, atmosConfig *schema.AtmosConfiguration)
- func FormatBytes(b int64) string
- func FormatDuration(d time.Duration) string
- func SelfBaselineTakenAt() time.Time
- type ProcessMetrics
- type Snapshot
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Accumulate ¶ added in v1.229.0
func Accumulate(m *ProcessMetrics)
Accumulate adds m's resource usage into the process-wide running total. Safe for concurrent use. A nil m is a no-op.
func DisplayFinalSummary ¶ added in v1.229.0
func DisplayFinalSummary(atmosConfig *schema.AtmosConfiguration)
DisplayFinalSummary prints a single aggregate resource-usage summary at the very end of the whole atmos invocation: the atmos process's own usage combined with the accumulated usage of every subprocess spawned during the run (e.g. every component plan in a multi-component --affected run). No-ops when local display is disabled, or when no subprocess metrics were ever accumulated (e.g. commands with no subprocess, such as `describe affected`, don't need a second/duplicate line — their own self-usage is already reported by the normal exec-metadata path).
func DisplaySummary ¶ added in v1.229.0
func DisplaySummary(label string, m ProcessMetrics, atmosConfig *schema.AtmosConfiguration)
DisplaySummary prints a one-line local resource-usage summary via ui.Info, gated by settings.metrics.enabled (default true). Label identifies the scope of the measurement (e.g. "Completed", "Total"). This message is rendered as markdown (see pkg/ui/formatter.go's toastMarkdown), so the two numbers most relevant to sizing a CI runner — wall time and peak memory — are bolded; CPU time is left plain as supporting detail. Bold degrades to plain text with no stray "**" in non-TTY/no-color output (confirmed via manual testing — Glamour strips markdown syntax rather than emitting ANSI when color is unsupported), so this has no effect on golden-snapshot output.
func FormatBytes ¶ added in v1.229.0
FormatBytes formats bytes into a human-readable string (e.g. "512.0 MB"). Exported for the same cross-package formatting-consistency reason as FormatDuration.
func FormatDuration ¶ added in v1.229.0
FormatDuration formats a duration for human display (e.g. "45.2s", "800ms"). Exported so other packages that render resource-usage numbers alongside Atmos's own local display — e.g. the Native CI job-summary templates — produce identically formatted values.
func SelfBaselineTakenAt ¶ added in v1.229.0
SelfBaselineTakenAt returns the instant selfBaseline was captured (as early as possible in the process's lifetime). Used to compute the whole invocation's wall-clock time for the final aggregate summary.
Types ¶
type ProcessMetrics ¶
type ProcessMetrics struct {
WallTime time.Duration
UserCPUTime time.Duration
SystemCPUTime time.Duration
// MaxRSSBytes is the kernel's ru_maxrss for the sample (RUSAGE_SELF for
// Atmos's own usage, or the wait4(2)-reported rusage for a subprocess
// tree). For a subprocess tree specifically, ru_maxrss is documented as
// the peak RSS of the single largest process among the child and its own
// already-reaped descendants — NOT the simultaneous sum of every
// concurrently running process's RSS. If Terraform and two provider
// plugins each peak at 200MB at the same moment, this reports ~200MB,
// not ~600MB. Treat it as a lower bound on true peak memory, not an
// exact whole-tree figure — hence every user-facing label calls it "peak
// memory (largest process)", not simply "peak memory".
MaxRSSBytes int64
MinorPageFaults int64
MajorPageFaults int64
InBlockOps int64
OutBlockOps int64
VolCtxSwitches int64
InvolCtxSwitches int64
}
ProcessMetrics captures how much time and system resources a process (or a process tree) consumed. Fields not available on the current platform (e.g. Windows) are left zero-valued; callers that marshal this struct should use omitempty for those fields.
func AccumulatedTotal ¶ added in v1.229.0
func AccumulatedTotal() ProcessMetrics
AccumulatedTotal returns the running total accumulated so far via Accumulate. Returns the zero value if Accumulate was never called.
func CollectFromProcessState ¶ added in v1.229.0
func CollectFromProcessState(cmd *exec.Cmd, wallTime time.Duration) *ProcessMetrics
CollectFromProcessState extracts resource-usage metrics for a subprocess tree — the given cmd and, on Unix, all of its children — from cmd.ProcessState after cmd.Wait() has returned. On Unix, ProcessState.UserTime()/SystemTime() aggregate "the exited process and its children" (Go's documented behavior, backed by wait4(2)'s rusage), and ProcessState.SysUsage() additionally exposes the same aggregate for memory/page-fault/context-switch/block-I/O counters. On Windows, Go's UserTime()/SystemTime() are backed by GetProcessTimes, which reports only the named process, not its descendants — so Windows CPU-time metrics cover cmd itself alone, excluding any child processes it spawns (e.g. Terraform provider plugins). Safe to call with a nil cmd or a nil ProcessState (e.g. the process never started): only WallTime is populated in that case.
func Combine ¶ added in v1.229.0
func Combine(a, b ProcessMetrics) ProcessMetrics
Combine sums two ProcessMetrics samples field-by-field, taking the max for MaxRSSBytes (a peak value, not an additive counter). Note that max() here does not recover a true simultaneous whole-tree peak either — see ProcessMetrics.MaxRSSBytes's doc comment — it only ever narrows down to the single largest process observed across both samples.
WallTime is deliberately left at its zero value in the result: when a child process runs synchronously inside a parent's measured window, the child's wall time is already nested inside the parent's elapsed wall time, so summing the two would double-count. Callers combining metrics MUST set the result's WallTime explicitly from their own elapsed-time measurement (e.g. time.Since). Do not "fix" this by adding WallTime to the sum below.
func SelfUsageSoFar ¶ added in v1.229.0
func SelfUsageSoFar() ProcessMetrics
SelfUsageSoFar returns the atmos process's own resource usage accumulated since package load. This measures only the atmos process itself, never any subprocess it spawns — see CollectFromProcessState for subprocess-tree usage.
type Snapshot ¶
type Snapshot struct {
// contains filtered or unexported fields
}
Snapshot is a point-in-time capture of process resource usage, taken as early as possible in the process lifetime, used later to compute a diff via Since().
func Baseline ¶
func Baseline() Snapshot
Baseline captures a Snapshot as early as possible in the process's lifetime. Both the async and synchronous exec-metadata capture paths diff against the same baseline.
func (*Snapshot) Since ¶
func (s *Snapshot) Since() ProcessMetrics
Since computes the ProcessMetrics accumulated since the Snapshot was taken.
Source Files