gmeasure

gmeasure: benchmarking and measuring code

gmeasure records benchmarks as Experiments that hold one or more named Measurements. Use it standalone (fmt.Println(experiment)) or wire it into Ginkgo for rich report output. Docs: https://onsi.github.io/gomega/#gmeasure-benchmarking-code. For the broader library see gomega:overview.

import "github.com/onsi/gomega/gmeasure"

Mental model

• An Experiment (gmeasure.NewExperiment(name)) groups related measurements for one system/context.
• A Measurement is a named bag of data points plus a Type: MeasurementTypeValue (float64) or MeasurementTypeDuration (time.Duration). It is created on its first recorded data point; later records of the same name append.
• Stats are statistical aggregates (min/max/mean/median/stddev) computed over a measurement's data points.

gmeasure does not fail tests by itself. It is a benchmarking/reporting tool. To gate on results you must pull Stats and write your own Expect(...) (or use RankStats(...).Winner()).

experiment := gmeasure.NewExperiment("My Experiment")
experiment.RecordDuration("runtime", 3*time.Second) // creates the "runtime" measurement
experiment.RecordDuration("runtime", 5*time.Second) // appends a data point

Recording values and durations

// Direct values / durations:
experiment.RecordValue("length", 3.141)
experiment.RecordDuration("runtime", 200*time.Millisecond)

// Callback-driven — gmeasure times MeasureDuration for you:
v := experiment.MeasureValue("length", func() float64 { return computeLength() })
d := experiment.MeasureDuration("save", func() { client.Save(model) })

Experiments are thread-safe — RecordX/MeasureX may be called from any goroutine.

Sampling: ensembles of data points

Run a callback repeatedly to build up many data points. Configure with SamplingConfig:

type SamplingConfig struct {
	N                   int           // cap on number of samples
	Duration            time.Duration // cap on total sampling time
	NumParallel         int           // run samples across this many goroutines (>1)
	MinSamplingInterval time.Duration // minimum gap between samples (incompatible with NumParallel)
}