procstats

package
v1.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 14, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package procstats measures per-process CPU and RSS over a reset-to-snapshot interval using Linux procfs. The filesystem is injectable so parsing and interval behavior can be tested on every development platform.

Index

Constants

View Source 
const (
	// CollectorName is the immutable run snapshot section populated by this
	// collector.
	CollectorName = "proc"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type CPUTotal added in v0.5.0 

type CPUTotal struct {
	BusyPercent   float64 `json:"busyPercent"`
	UserPercent   float64 `json:"userPercent"`
	SystemPercent float64 `json:"systemPercent"`
	IOWaitPercent float64 `json:"iowaitPercent"`
	StealPercent  float64 `json:"stealPercent"`
	IdlePercent   float64 `json:"idlePercent"`
}

CPUTotal is the whole-machine utilization over the interval, following top's %Cpu(s) convention where all cores together are 100%. It answers "is the hardware actually saturated, or is capacity left idle?".

type Collector 

type Collector struct {
	// contains filtered or unexported fields
}

Collector owns a baseline and produces interval snapshots. Reset and Snapshot are serialized so a baseline cannot be changed mid-scan.

func New 

func New(options ...Option) *Collector

New creates an idle collector. Call Reset immediately before the measured interval and Snapshot after it.

func (*Collector) CaptureBaseline added in v1.2.0 

func (c *Collector) CaptureBaseline(ctx context.Context, runID string, ep runctl.Epoch) (runctl.SampleResult, error)

CaptureBaseline resets procstats at the coordinated opening boundary. A retry for the same run and epoch replays the first committed result instead of moving the baseline forward.

func (*Collector) CaptureFinal added in v1.2.0 

func (c *Collector) CaptureFinal(ctx context.Context, runID string, ep runctl.Epoch) (runctl.SampleResult, error)

CaptureFinal freezes the process snapshot at the coordinated closing boundary. Report rendering later reads this immutable value and never extends the interval to dashboard/save time.

func (*Collector) Collect added in v1.2.0 

func (c *Collector) Collect(base, final runctl.BaselineHandle) (any, error)

Collect returns the snapshot frozen by CaptureFinal. It reads only the two handles, so neither a later dashboard refresh nor a delayed save can change the measured process interval.

func (*Collector) Health 

func (c *Collector) Health() Health

Health returns a copy of the most recent Reset or Snapshot health.

func (*Collector) Name added in v1.2.0 

func (c *Collector) Name() string

Name identifies the immutable section this collector contributes to a run.

func (*Collector) Release added in v1.2.0 

func (c *Collector) Release(h runctl.BaselineHandle)

Release forgets retry bookkeeping. The handle itself retains a deep copy of its boundary, so release cannot change an interval already being collected.

func (*Collector) Reset 

func (c *Collector) Reset() error

Reset captures the interval baseline. Per-process failures are recorded in Health and do not fail Reset. A missing or malformed aggregate /proc/stat makes the interval unavailable and is returned to the caller.

func (*Collector) Snapshot 

func (c *Collector) Snapshot() Snapshot

Snapshot reads the interval end and returns CPU and RSS top lists. Collection errors are reflected in Snapshot.Health instead of panicking or terminating the application.

func (*Collector) TimelinePoint added in v1.4.0 

func (c *Collector) TimelinePoint() (Point, error)

TimelinePoint reads the cumulative counters needed by the optional run-aligned timeline. It shares the collector lock with boundary snapshots so procfs reads cannot interleave with a reset.

type Health 

type Health struct {
	Status  Status   `json:"status"`
	Partial bool     `json:"partial"`
	Dropped uint64   `json:"dropped"`
	Errors  []string `json:"errors,omitempty"`
}

Health describes collection failures without making the measured application fail. Errors is bounded; Dropped always contains the full count.

type Option 

type Option func(*Collector)

Option configures a Collector.

func WithClock 

func WithClock(now func() time.Time) Option

WithClock supplies wall time for interval metadata.

func WithClockTicks 

func WithClockTicks(ticks uint64) Option

WithClockTicks sets USER_HZ used to convert process jiffies to seconds. Linux is normally 100; injection avoids a libc dependency and enables tests.

func WithFS 

func WithFS(fsys fs.FS) Option

WithFS supplies a procfs-like filesystem. It is primarily intended for deterministic tests and non-Linux development hosts.

func WithPageSize 

func WithPageSize(bytes uint64) Option

WithPageSize sets the byte size used for statm resident pages.

func WithProcRoot 

func WithProcRoot(root string) Option

WithProcRoot selects a procfs root. The default is /proc.

func WithTopN 

func WithTopN(n int) Option

WithTopN sets the maximum number of entries in each CPU and RSS list.

func WithTrackedPIDs added in v1.2.0 

func WithTrackedPIDs(pids ...int) Option

WithTrackedPIDs marks process identities whose loss must make an interval partial. Host-wide process churn is expected, so an untracked PID that exits between boundaries is ignored; a tracked PID that exits is measurement loss. Non-positive PIDs are ignored.

type Point added in v1.4.0 

type Point struct {
	TotalJiffies   uint64
	BusyJiffies    uint64
	IOWaitJiffies  uint64
	ProcessJiffies uint64
	CPUs           int
	RSSBytes       uint64
}

Point is one cumulative process/host CPU reading for time-bucket deltas. It intentionally contains no command names or per-PID rows.

type Process 

type Process struct {
	PID          int     `json:"pid"`
	Command      string  `json:"command"`
	CPUPercent   float64 `json:"cpuPercent"`
	CPUSeconds   float64 `json:"cpuSeconds"`
	RSSBytes     uint64  `json:"rssBytes"`
	DeltaJiffies uint64  `json:"deltaJiffies"`
	Starttime    uint64  `json:"starttime"`
	Appeared     bool    `json:"appeared,omitempty"`
	PIDReused    bool    `json:"pidReused,omitempty"`
}

Process is one process's reset-to-snapshot CPU delta and end-of-interval RSS.

type Snapshot 

type Snapshot struct {
	StartedAt       time.Time `json:"startedAt"`
	EndedAt         time.Time `json:"endedAt"`
	IntervalJiffies uint64    `json:"intervalJiffies"`
	CPUs            int       `json:"cpus"`
	CPUTotal        *CPUTotal `json:"cpuTotal,omitempty"`
	TopCPU          []Process `json:"topCPU"`
	TopRSS          []Process `json:"topRSS"`
	Health          Health    `json:"health"`
}

Snapshot is the process report for the current reset-to-snapshot interval. CPU percent follows top: one fully occupied core is 100%.

type Status 

type Status string

Status summarizes whether a collector produced a complete interval. 

const (
	StatusOK          Status = "ok"
	StatusPartial     Status = "partial"
	StatusUnavailable Status = "unavailable"
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.