goruntime

Documentation

Overview

Package goruntime reads the running process's own Go runtime metrics (runtime/metrics) into a caller-owned Snapshot. It is the portable counterpart to the Linux-only sysmetrics collector: the same Bundle-style "fill a snapshot" shape (see Collector.Read) over the platform-independent runtime/metrics surface — heap occupancy, GC accounting, scheduler state.

Portability: the collector carries no platform or feature build tags. It runs on every GOOS/GOARCH the Go toolchain supports.

Version tolerance: the curated metric set is intersected with metrics.All() at construction, so a metric that a given Go release does not expose is simply not requested and its Snapshot field stays zero. Snapshot.Missing reports how many curated metrics were absent.

Observer effect: this collector measures the process it runs in. Collector.Read is built to perturb that process as little as possible — it reuses its sample buffer and the histogram slice backings, allocating nothing in steady state, and it reads exclusively through runtime/metrics (which, unlike runtime.ReadMemStats, does not stop the world). See ADR-0061 for the wider dashboard this feeds.

Index

• Constants
• Variables
• type Collector
  • func NewCollector() (inst *Collector)
  • func (inst *Collector) Read(snap *Snapshot) (err error)
• type Histogram
• type Snapshot

Constants

const MemLimitUnset uint64 = math.MaxInt64

MemLimitUnset is the value runtime/metrics reports for /gc/gomemlimit:bytes when GOMEMLIMIT is not configured (math.MaxInt64). Callers treat a Snapshot.GOMemLimit equal to this as "no soft memory limit set".

Variables

var PackageProps = packageprops.Props{
	WASMWASI:         packageprops.WASMCompiles,
	WASMJS:           packageprops.WASMCompiles,
	WASMFreestanding: packageprops.WASMCompiles,
}

PackageProps records this package's curated properties (ADR-0080). Seeded by `boxer code analysis golang wasmsurvey props generate`; curate by hand. The same group's `props verify` reconciles it.

Types

type Collector

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

Collector reads a curated subset of runtime/metrics into a Snapshot. It owns a reusable sample buffer sized to the metrics actually present on this runtime; construct once and Read many times.

func NewCollector

func NewCollector() (inst *Collector)

NewCollector builds a Collector over the package's curated metric set, intersected with what the running Go version exposes.

func (*Collector) Read

func (inst *Collector) Read(snap *Snapshot) (err error)

Read fills snap in place from a single metrics.Read. Allocation-free in steady state. The returned error is always nil today; it is part of the surface so a future validation step does not break callers.

type Histogram

type Histogram struct {
	Buckets []float64
	Counts  []uint64
}

Histogram mirrors metrics.Float64Histogram: Counts has len(Buckets)-1 entries and is cumulative since process start. The zero value is an empty, safe-to-read histogram.

type Snapshot

type Snapshot struct {
	// Memory classes (bytes). These partition TotalMapped; the dashboard bands
	// them as objects / idle (free+unused+released) / stacks / metadata / other.
	HeapObjects  uint64
	HeapFree     uint64
	HeapReleased uint64
	HeapUnused   uint64
	HeapStacks   uint64
	OSStacks     uint64
	Metadata     uint64 // summed /memory/classes/metadata/*
	Other        uint64 // /memory/classes/other + /memory/classes/profiling/buckets
	TotalMapped  uint64

	// GC heap accounting.
	HeapGoal         uint64 // /gc/heap/goal: the GC's target heap size for the next cycle
	HeapLive         uint64 // /gc/heap/live, or allocs-frees when that metric is absent
	HeapObjectsCount uint64
	AllocBytes       uint64 // cumulative bytes allocated
	FreeBytes        uint64 // cumulative bytes freed
	AllocObjects     uint64 // cumulative objects allocated
	FreeObjects      uint64 // cumulative objects freed

	// GC cycles (cumulative counts).
	GCCyclesTotal  uint64
	GCCyclesForced uint64

	// Scheduler.
	Goroutines uint64
	GomaxProcs uint64

	// Knobs (read-only; the dashboard never mutates these).
	GOGCPercent uint64
	GOMemLimit  uint64 // MemLimitUnset when GOMEMLIMIT is not configured

	// Misc.
	MutexWaitSec float64 // cumulative seconds goroutines blocked on mutexes

	// Cumulative histograms. Captured here so the GC and Scheduler panels (later
	// milestones) inherit a populated collector; the Heap panel does not read them.
	GCPauses       Histogram // /gc/pauses:seconds
	SchedLatencies Histogram // /sched/latencies:seconds
	// STW pause distributions (Go 1.22+); empty when the running Go lacks them.
	SchedPausesGC    Histogram // /sched/pauses/total/gc:seconds
	SchedPausesOther Histogram // /sched/pauses/total/other:seconds

	// Missing counts curated metrics absent from metrics.All() on this runtime.
	Missing int
}

Snapshot is a point-in-time read of the Go runtime's metrics. Callers own the value and reuse it across Collector.Read calls; in steady state Read performs no allocation (the histogram slice backings are reused via append-to-truncated). A scalar field is zero when its backing metric is absent on the running Go version — indistinguishable from a genuine zero, which is acceptable for the metrics here (a real runtime never has zero goroutines or zero mapped memory).