runtimebudget

README

runtimebudget

runtimebudget is a Go 1.23, standard-library-only package for reading and comparing runtime/metrics snapshots.

const name = "/gc/cycles/total:gc-cycles"

before := runtimebudget.Read(name)
// ... work ...
after := runtimebudget.Read(name)

delta, err := runtimebudget.Delta(before, after, name)
if err != nil {
	return err
}
count, ok := delta.Uint64()
_ = count
_ = ok

rate, err := runtimebudget.Rate(before, after, name)

Read() and ReadAll() read all metrics; passing names reads only those metrics. A name unknown to the current Go runtime is retained as KindBad. Snapshot.Get also distinguishes a missing name from a present KindBad value. Value.Uint64, Value.Float64, and Value.Histogram return (value, false) instead of panicking for the wrong kind.

Delta and Rate only accept cumulative scalar metrics, as declared by runtime/metrics.Description.Cumulative. A counter decrease is reported as ErrCounterReset. Histograms are never converted to a scalar: use HistogramDelta for per-bucket count differences. Divide those counts by current.At().Sub(previous.At()).Seconds() when a bucket rate is needed.

For non-cumulative scalar metrics, check maximum budgets:

report := runtimebudget.Check(snapshot, map[string]float64{
	"/gc/heap/goal:bytes": 64 << 20,
})
if err := report.Err(); err != nil {
	// errors.Is(err, runtimebudget.ErrBudgetExceeded) identifies violations.
	// report.Violations contains their values and limits; report.Issues contains
	// unknown, missing, KindBad, histogram, and other unevaluable metrics.
	return err
}

The runtime metrics API is implementation-defined and evolves with Go. This package consults runtime/metrics.All() at runtime rather than maintaining its own metric list.

API reference: runtime/metrics package, Go source.

Documentation

Overview

Package runtimebudget reads runtime/metrics snapshots and compares them.

Index

• Variables
• func Rate(previous, current Snapshot, name string) (float64, error)
• type Histogram
  • func HistogramDelta(previous, current Snapshot, name string) (Histogram, error)
• type Issue
  • func (i Issue) Error() string
• type Report
  • func Check(snapshot Snapshot, budgets map[string]float64) Report
  • func (r Report) Err() error
  • func (r Report) OK() bool
• type ReportError
  • func (e *ReportError) Error() string
  • func (e *ReportError) Unwrap() []error
• type Snapshot
  • func Read(names ...string) Snapshot
  • func ReadAll() Snapshot
  • func (s Snapshot) At() time.Time
  • func (s Snapshot) Get(name string) (Value, bool)
  • func (s Snapshot) Names() []string
• type Value
  • func Delta(previous, current Snapshot, name string) (Value, error)
  • func (v Value) Float64() (float64, bool)
  • func (v Value) Histogram() (Histogram, bool)
  • func (v Value) Kind() metrics.ValueKind
  • func (v Value) Uint64() (uint64, bool)
• type Violation
  • func (v Violation) Error() string

Variables

var (
	// ErrUnknownMetric means the metric name is not in runtime/metrics.All.
	ErrUnknownMetric = errors.New("runtimebudget: unknown metric")
	// ErrMetricMissing means a snapshot does not contain the requested metric.
	ErrMetricMissing = errors.New("runtimebudget: metric missing from snapshot")
	// ErrMetricUnavailable means runtime/metrics returned KindBad.
	ErrMetricUnavailable = errors.New("runtimebudget: metric unavailable")
	// ErrKindMismatch means a value's kind differs from its runtime description.
	ErrKindMismatch = errors.New("runtimebudget: metric kind mismatch")
	// ErrUnsupportedKind means a newer or otherwise unsupported metric kind was seen.
	ErrUnsupportedKind = errors.New("runtimebudget: unsupported metric kind")
	// ErrNotCumulative means an operation requiring a cumulative metric was requested.
	ErrNotCumulative = errors.New("runtimebudget: metric is not cumulative")
	// ErrHistogramScalarDelta means a histogram was passed to scalar Delta or Rate.
	ErrHistogramScalarDelta = errors.New("runtimebudget: histogram needs bucket handling")
	// ErrHistogramRequired means HistogramDelta was passed a non-histogram metric.
	ErrHistogramRequired = errors.New("runtimebudget: metric is not a histogram")
	// ErrHistogramLayout means two histogram snapshots have different bucket boundaries.
	ErrHistogramLayout = errors.New("runtimebudget: histogram bucket layout mismatch")
	// ErrCounterReset means a cumulative value decreased between snapshots.
	ErrCounterReset = errors.New("runtimebudget: cumulative metric decreased")
	// ErrInvalidInterval means the current snapshot is not after the previous one.
	ErrInvalidInterval = errors.New("runtimebudget: snapshot interval must be positive")
	// ErrInvalidBudget means a budget limit is NaN or infinite.
	ErrInvalidBudget = errors.New("runtimebudget: budget limit must be finite")
	// ErrHistogramBudget means a histogram cannot be checked as one scalar value.
	ErrHistogramBudget = errors.New("runtimebudget: histogram budget needs bucket handling")
	// ErrBudgetExceeded means at least one budget was exceeded.
	ErrBudgetExceeded = errors.New("runtimebudget: budget exceeded")
)

Functions

func Rate

func Rate(previous, current Snapshot, name string) (float64, error)

Rate returns the scalar cumulative increase per second, using the timestamps captured in the two snapshots. Histograms are intentionally rejected.

Types

type Histogram

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

Histogram is an explicit bucketed metric value. Counts[i] covers [Buckets[i], Buckets[i+1]).

func HistogramDelta

func HistogramDelta(previous, current Snapshot, name string) (Histogram, error)

HistogramDelta returns per-bucket increases for a cumulative histogram. Buckets are copied from the current snapshot.

type Issue

type Issue struct {
	Name string
	Err  error
}

Issue describes a budget that could not be evaluated.

func (Issue) Error

func (i Issue) Error() string

type Report

type Report struct {
	Violations []Violation
	Issues     []Issue
}

Report contains budget violations and metrics that could not be checked.

func Check

func Check(snapshot Snapshot, budgets map[string]float64) Report

Check evaluates maximum numeric budgets for non-cumulative scalar metrics. The returned report is deterministic by metric name. Use report.Err() when the caller wants violations and evaluation issues as an error.

func (Report) Err

func (r Report) Err() error

Err converts a non-OK report into a clear, inspectable error.

func (Report) OK

func (r Report) OK() bool

OK reports whether every budget was evaluated and satisfied.

type ReportError

type ReportError struct {
	Report Report
}

ReportError is returned by Report.Err when a check has violations or issues.

func (*ReportError) Error

func (e *ReportError) Error() string

func (*ReportError) Unwrap

func (e *ReportError) Unwrap() []error

Unwrap makes errors.Is useful for both violations and evaluation issues.

type Snapshot

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

Snapshot is an immutable copy of selected runtime metrics at one point in time. The snapshot's histogram slices are copied, so a later runtime/metrics.Read does not change this snapshot.

func Read

func Read(names ...string) Snapshot

Read reads the named metrics. With no names, it reads every metric currently returned by runtime/metrics.All. Unknown names are retained with KindBad.

func ReadAll

func ReadAll() Snapshot

ReadAll reads every metric currently returned by runtime/metrics.All.

func (Snapshot) At

func (s Snapshot) At() time.Time

At reports when the snapshot was captured.

func (Snapshot) Get

func (s Snapshot) Get(name string) (Value, bool)

Get returns a metric value and whether the snapshot contains that name. A present but unsupported or unknown runtime metric has KindBad and still returns true.

func (Snapshot) Names

func (s Snapshot) Names() []string

Names returns the metric names in the snapshot in sorted order.

type Value

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

Value is a kind-tagged runtime metric value.

func Delta

func Delta(previous, current Snapshot, name string) (Value, error)

Delta returns the scalar increase of a cumulative metric. Histograms are intentionally rejected; use HistogramDelta for their bucket counts.

func (Value) Float64

func (v Value) Float64() (float64, bool)

Float64 returns the value when its kind is KindFloat64.

func (Value) Histogram

func (v Value) Histogram() (Histogram, bool)

Histogram returns a copy when its kind is KindFloat64Histogram.

func (Value) Kind

func (v Value) Kind() metrics.ValueKind

Kind reports the runtime/metrics kind of the value.

func (Value) Uint64

func (v Value) Uint64() (uint64, bool)

Uint64 returns the value when its kind is KindUint64.

type Violation

type Violation struct {
	Name  string
	Value float64
	Limit float64
	Kind  metrics.ValueKind
}

Violation describes one numeric value above its configured maximum.

func (Violation) Error

func (v Violation) Error() string