github.com/rcrowley/go-metrics v0.0.0-20250401214520-65e299d6c5c9: record and sample values with Histogram in go-metrics

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: record and sample values with Histogram in go-metrics
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/rcrowley/go-metrics@v0.0.0-20250401214520-65e299d6c5c9
Demonstrate these symbols/APIs:
  - metrics.NewExpDecaySample
  - metrics.NewHistogram
  - metrics.NewUniformSample

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:6e281b4ae39b6223d930820ad7d3f3d7b924b670552ba3234fc9a78a9bacb6e5","contract":["metrics.NewHistogram constructs a new histogram with the given sample reservoir","Histogram.Update records values into the histogram reservoir and updates count, min, max, and sum","Histogram.Mean, Variance, and StdDev calculate statistical distribution measures from recorded values","Histogram.Percentile and Percentiles calculate distribution percentiles","Histogram.Snapshot captures an immutable point-in-time snapshot with statistical metrics","metrics.NewUniformSample creates a sample maintaining a uniform reservoir of values","metrics.NewExpDecaySample creates an exponentially decaying sample favoring recent values","Histogram.Clear resets all recorded statistics in the histogram"],"goal":"record and sample values with Histogram in go-metrics","kind":"HOW","packages":["pkg:golang/github.com/rcrowley/go-metrics@v0.0.0-20250401214520-65e299d6c5c9"],"schemaVersion":1,"symbols":["metrics.NewExpDecaySample","metrics.NewHistogram","metrics.NewUniformSample"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/rcrowley/go-metrics@v0.0.0-20250401214520-65e299d6c5c9"],"schemaVersion":1,"subject":"pkg:golang/github.com/rcrowley/go-metrics@v0.0.0-20250401214520-65e299d6c5c9","symbols":["metrics.NewExpDecaySample","metrics.NewHistogram","metrics.NewUniformSample"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.22

require github.com/rcrowley/go-metrics v0.0.0-20250401214520-65e299d6c5c9

github.com/rcrowley/go-metrics v0.0.0-20250401214520-65e299d6c5c9 h1:bsUq1dX0N8AOIL7EB/X911+m4EHsnWEHeJ0c+3TTBrg=
github.com/rcrowley/go-metrics v0.0.0-20250401214520-65e299d6c5c9/go.mod h1:bCqnVzQkZxMG4s8nGwiZ5l3QUCyqpo9Y+/ZMZ9VjZe4=

package main

import (
	"fmt"

	"github.com/rcrowley/go-metrics"
)

func main() {
	// Create a uniform sample with reservoir size of 100
	uniformSample := metrics.NewUniformSample(100)
	uniformHist := metrics.NewHistogram(uniformSample)

	// Create an exponentially-decaying sample with reservoir size 100 and alpha 0.015
	expDecaySample := metrics.NewExpDecaySample(100, 0.015)
	expHist := metrics.NewHistogram(expDecaySample)

	// Record values into histograms
	for i := int64(1); i <= 100; i++ {
		uniformHist.Update(i)
		expHist.Update(i)
	}

	// Capture snapshots and display metrics
	uSnap := uniformHist.Snapshot()
	fmt.Printf("Uniform Histogram count: %d, mean: %.2f, 95th percentile: %.2f\n",
		uSnap.Count(), uSnap.Mean(), uSnap.Percentile(0.95))

	eSnap := expHist.Snapshot()
	fmt.Printf("ExpDecay Histogram count: %d, mean: %.2f, 95th percentile: %.2f\n",
		eSnap.Count(), eSnap.Mean(), eSnap.Percentile(0.95))
}

{
  "schemaVersion": 1,
  "goal": "record and sample values with Histogram in go-metrics",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/rcrowley/go-metrics@v0.0.0-20250401214520-65e299d6c5c9"
  ],
  "symbols": [
    "metrics.NewExpDecaySample",
    "metrics.NewHistogram",
    "metrics.NewUniformSample"
  ]
}

package main

import (
	"fmt"
	"math"
	"os"

	"github.com/rcrowley/go-metrics"
)

func main() {
	// 1. metrics.NewHistogram constructs a new histogram with the given sample reservoir
	s := metrics.NewUniformSample(100)
	h := metrics.NewHistogram(s)
	if h == nil {
		fmt.Fprintf(os.Stderr, "metrics.NewHistogram returned nil\n")
		os.Exit(1)
	}
	if h.Count() != 0 {
		fmt.Fprintf(os.Stderr, "expected initial count 0, got %d\n", h.Count())
		os.Exit(1)
	}
	if h.Min() != 0 || h.Max() != 0 || h.Sum() != 0 {
		fmt.Fprintf(os.Stderr, "expected initial min=0 max=0 sum=0, got min=%d max=%d sum=%d\n", h.Min(), h.Max(), h.Sum())
		os.Exit(1)
	}

	// 2. Histogram.Update records values into the histogram reservoir and updates count, min, max, and sum
	h.Update(10)
	h.Update(20)
	h.Update(30)
	if h.Count() != 3 {
		fmt.Fprintf(os.Stderr, "expected count 3 after updates, got %d\n", h.Count())
		os.Exit(1)
	}
	if h.Min() != 10 {
		fmt.Fprintf(os.Stderr, "expected min 10, got %d\n", h.Min())
		os.Exit(1)
	}
	if h.Max() != 30 {
		fmt.Fprintf(os.Stderr, "expected max 30, got %d\n", h.Max())
		os.Exit(1)
	}
	if h.Sum() != 60 {
		fmt.Fprintf(os.Stderr, "expected sum 60, got %d\n", h.Sum())
		os.Exit(1)
	}

	// 3. Histogram.Mean, Variance, and StdDev calculate statistical distribution measures from recorded values
	if math.Abs(h.Mean()-20.0) > 0.001 {
		fmt.Fprintf(os.Stderr, "expected mean 20.0, got %f\n", h.Mean())
		os.Exit(1)
	}
	if h.Variance() <= 0.0 || h.StdDev() <= 0.0 {
		fmt.Fprintf(os.Stderr, "expected positive variance and stddev, got var=%f stddev=%f\n", h.Variance(), h.StdDev())
		os.Exit(1)
	}

	// 4. Histogram.Percentile and Percentiles calculate distribution percentiles
	p50 := h.Percentile(0.50)
	p95 := h.Percentile(0.95)
	if p50 <= 0 || p95 <= 0 || p50 > p95 {
		fmt.Fprintf(os.Stderr, "unexpected percentiles: p50=%f p95=%f\n", p50, p95)
		os.Exit(1)
	}
	percentiles := h.Percentiles([]float64{0.25, 0.50, 0.75, 0.99})
	if len(percentiles) != 4 {
		fmt.Fprintf(os.Stderr, "expected 4 percentiles, got %d\n", len(percentiles))
		os.Exit(1)
	}
	for i := 1; i < len(percentiles); i++ {
		if percentiles[i-1] > percentiles[i] {
			fmt.Fprintf(os.Stderr, "expected non-decreasing percentiles, got %v\n", percentiles)
			os.Exit(1)
		}
	}

	// 5. Histogram.Snapshot captures an immutable point-in-time snapshot with statistical metrics
	snap := h.Snapshot()
	if snap == nil {
		fmt.Fprintf(os.Stderr, "Snapshot returned nil\n")
		os.Exit(1)
	}
	if snap.Count() != 3 {
		fmt.Fprintf(os.Stderr, "expected snapshot count 3, got %d\n", snap.Count())
		os.Exit(1)
	}
	h.Update(100)
	if snap.Count() != 3 {
		fmt.Fprintf(os.Stderr, "expected snapshot count to stay 3, got %d\n", snap.Count())
		os.Exit(1)
	}
	snapPanicked := false
	func() {
		defer func() {
			if recover() != nil {
				snapPanicked = true
			}
		}()
		snap.Update(50)
	}()
	if !snapPanicked {
		fmt.Fprintf(os.Stderr, "expected snap.Update to panic on snapshot\n")
		os.Exit(1)
	}

	// 6. metrics.NewUniformSample creates a sample maintaining a uniform reservoir of values
	uniformSample := metrics.NewUniformSample(50)
	if uniformSample == nil {
		fmt.Fprintf(os.Stderr, "metrics.NewUniformSample returned nil\n")
		os.Exit(1)
	}
	uniformHist := metrics.NewHistogram(uniformSample)
	for i := int64(1); i <= 100; i++ {
		uniformHist.Update(i)
	}
	if uniformHist.Count() != 100 {
		fmt.Fprintf(os.Stderr, "expected uniformHist count 100, got %d\n", uniformHist.Count())
		os.Exit(1)
	}
	if uniformHist.Sample().Size() != 50 {
		fmt.Fprintf(os.Stderr, "expected sample reservoir size 50, got %d\n", uniformHist.Sample().Size())
		os.Exit(1)
	}

	// 7. metrics.NewExpDecaySample creates an exponentially decaying sample favoring recent values
	expSample := metrics.NewExpDecaySample(50, 0.015)
	if expSample == nil {
		fmt.Fprintf(os.Stderr, "metrics.NewExpDecaySample returned nil\n")
		os.Exit(1)
	}
	expHist := metrics.NewHistogram(expSample)
	for i := int64(1); i <= 100; i++ {
		expHist.Update(i)
	}
	if expHist.Count() != 100 {
		fmt.Fprintf(os.Stderr, "expected expHist count 100, got %d\n", expHist.Count())
		os.Exit(1)
	}
	if expHist.Sample().Size() != 50 {
		fmt.Fprintf(os.Stderr, "expected expSample reservoir size 50, got %d\n", expHist.Sample().Size())
		os.Exit(1)
	}

	// 8. Histogram.Clear resets all recorded statistics in the histogram
	uniformHist.Clear()
	if uniformHist.Count() != 0 || uniformHist.Min() != 0 || uniformHist.Max() != 0 {
		fmt.Fprintf(os.Stderr, "expected cleared histogram to have 0 count/min/max\n")
		os.Exit(1)
	}

	fmt.Println("All go-metrics Histogram contract assertions passed.")
}