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

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: verify pkg:golang/github.com/rcrowley/go-metrics@v0.0.0-20250401214520-65e299d6c5c9
Kind: HOW

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

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:ecbfd05877c3fda924fe917a7ba7bc4e220ae181cf46126526f1bdfe79e66cb7","contract":["metrics.NewUniformSample constructs a uniform sample reservoir with specified capacity","metrics.NewHistogram constructs a standard histogram backed by a sample reservoir","Histogram.Update records sample values and increments Count","Histogram.Min and Max track extreme recorded values","Histogram.Mean and Sum calculate arithmetic mean and total sum","Histogram.Variance and StdDev compute statistical dispersion","Histogram.Percentiles computes percentiles over the sample distribution","Histogram.Snapshot captures an immutable point-in-time snapshot of the histogram","metrics.GetOrRegisterHistogram registers a new histogram or returns an existing one from a registry"],"goal":"verify pkg:golang/github.com/rcrowley/go-metrics@v0.0.0-20250401214520-65e299d6c5c9","kind":"HOW","packages":["pkg:golang/github.com/rcrowley/go-metrics@v0.0.0-20250401214520-65e299d6c5c9"],"schemaVersion":1},"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","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 metrics registry
	registry := metrics.NewRegistry()

	// Create a uniform sample reservoir with capacity 100
	sample := metrics.NewUniformSample(100)

	// Create and register a histogram
	hist := metrics.NewHistogram(sample)
	if err := registry.Register("latency.histogram", hist); err != nil {
		panic(err)
	}

	// Record sample values
	values := []int64{10, 20, 30, 40, 50}
	for _, v := range values {
		hist.Update(v)
	}

	// Register or get an existing histogram
	cachedHist := metrics.GetOrRegisterHistogram("response.time", registry, metrics.NewUniformSample(100))
	cachedHist.Update(125)

	// Print histogram summary statistics
	h := registry.Get("latency.histogram").(metrics.Histogram)
	fmt.Printf("count: %d\n", h.Count())
	fmt.Printf("min: %d\n", h.Min())
	fmt.Printf("max: %d\n", h.Max())
	fmt.Printf("mean: %.2f\n", h.Mean())
	fmt.Printf("variance: %.2f\n", h.Variance())
	fmt.Printf("stddev: %.2f\n", h.StdDev())

	percentiles := h.Percentiles([]float64{0.50, 0.95, 0.99})
	fmt.Printf("p50: %.2f, p95: %.2f, p99: %.2f\n", percentiles[0], percentiles[1], percentiles[2])
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/github.com/rcrowley/go-metrics@v0.0.0-20250401214520-65e299d6c5c9",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/rcrowley/go-metrics@v0.0.0-20250401214520-65e299d6c5c9"
  ]
}

package main

import (
	"fmt"
	"math"
	"os"

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

func main() {
	// 1. metrics.NewUniformSample constructs a uniform sample reservoir with specified capacity
	s := metrics.NewUniformSample(100)
	if s == nil {
		fmt.Fprintf(os.Stderr, "metrics.NewUniformSample returned nil\n")
		os.Exit(1)
	}
	if s.Size() != 0 || s.Count() != 0 {
		fmt.Fprintf(os.Stderr, "expected initial sample size 0 and count 0, got size %d count %d\n", s.Size(), s.Count())
		os.Exit(1)
	}

	// 2. metrics.NewHistogram constructs a standard histogram backed by a sample reservoir
	h := metrics.NewHistogram(s)
	if h == nil {
		fmt.Fprintf(os.Stderr, "metrics.NewHistogram returned nil\n")
		os.Exit(1)
	}
	if h.Count() != 0 || h.Min() != 0 || h.Max() != 0 || h.Mean() != 0.0 {
		fmt.Fprintf(os.Stderr, "expected empty histogram values, got count=%d min=%d max=%d mean=%f\n", h.Count(), h.Min(), h.Max(), h.Mean())
		os.Exit(1)
	}

	// 3. Histogram.Update records sample values and increments Count
	h.Update(10)
	h.Update(20)
	h.Update(30)
	if h.Count() != 3 {
		fmt.Fprintf(os.Stderr, "expected count 3, got %d\n", h.Count())
		os.Exit(1)
	}

	// 4. Histogram.Min and Max track extreme recorded values
	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)
	}

	// 5. Histogram.Mean and Sum calculate arithmetic mean and total sum
	if h.Sum() != 60 {
		fmt.Fprintf(os.Stderr, "expected sum 60, got %d\n", h.Sum())
		os.Exit(1)
	}
	if math.Abs(h.Mean()-20.0) > 1e-9 {
		fmt.Fprintf(os.Stderr, "expected mean 20.0, got %f\n", h.Mean())
		os.Exit(1)
	}

	// 6. Histogram.Variance and StdDev compute statistical dispersion
	expectedVar := 200.0 / 3.0
	expectedStdDev := math.Sqrt(expectedVar)
	if math.Abs(h.Variance()-expectedVar) > 1e-9 {
		fmt.Fprintf(os.Stderr, "expected variance %f, got %f\n", expectedVar, h.Variance())
		os.Exit(1)
	}
	if math.Abs(h.StdDev()-expectedStdDev) > 1e-9 {
		fmt.Fprintf(os.Stderr, "expected stddev %f, got %f\n", expectedStdDev, h.StdDev())
		os.Exit(1)
	}

	// 7. Histogram.Percentiles computes percentiles over the sample distribution
	ps := h.Percentiles([]float64{0.50, 0.99})
	if len(ps) != 2 {
		fmt.Fprintf(os.Stderr, "expected 2 percentiles, got %d\n", len(ps))
		os.Exit(1)
	}
	if math.Abs(ps[0]-20.0) > 1e-9 {
		fmt.Fprintf(os.Stderr, "expected median 20.0, got %f\n", ps[0])
		os.Exit(1)
	}
	if math.Abs(ps[1]-30.0) > 1e-9 {
		fmt.Fprintf(os.Stderr, "expected p99 30.0, got %f\n", ps[1])
		os.Exit(1)
	}

	// 8. Histogram.Snapshot captures an immutable point-in-time snapshot of the histogram
	snap := h.Snapshot()
	if snap == nil || snap.Count() != 3 || snap.Max() != 30 {
		fmt.Fprintf(os.Stderr, "expected snapshot with count 3 and max 30, got count %d max %d\n", snap.Count(), snap.Max())
		os.Exit(1)
	}
	h.Update(100)
	if snap.Count() != 3 || snap.Max() != 30 {
		fmt.Fprintf(os.Stderr, "expected snapshot to remain unchanged after original updated\n")
		os.Exit(1)
	}
	panicked := false
	func() {
		defer func() {
			if recover() != nil {
				panicked = true
			}
		}()
		snap.Update(50)
	}()
	if !panicked {
		fmt.Fprintf(os.Stderr, "expected snap.Update to panic on snapshot\n")
		os.Exit(1)
	}

	// 9. metrics.GetOrRegisterHistogram registers a new histogram or returns an existing one from a registry
	reg := metrics.NewRegistry()
	hReg1 := metrics.GetOrRegisterHistogram("api.latency", reg, metrics.NewUniformSample(100))
	if hReg1 == nil {
		fmt.Fprintf(os.Stderr, "GetOrRegisterHistogram returned nil\n")
		os.Exit(1)
	}
	hReg1.Update(150)

	hReg2 := metrics.GetOrRegisterHistogram("api.latency", reg, metrics.NewUniformSample(100))
	if hReg2.Count() != 1 || hReg2.Max() != 150 {
		fmt.Fprintf(os.Stderr, "expected existing registered histogram with count 1 and max 150, got count %d max %d\n", hReg2.Count(), hReg2.Max())
		os.Exit(1)
	}
	hReg2.Update(250)
	if hReg1.Max() != 250 {
		fmt.Fprintf(os.Stderr, "expected both references to reflect updated max 250, got %d\n", hReg1.Max())
		os.Exit(1)
	}

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