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

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 metrics.GetOrRegisterHistogram in 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
Demonstrate these symbols/APIs:
  - metrics.GetOrRegisterHistogram

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:43f6c5979be7d4597b7cb32d1e1ec97aa9eb177fddb811e8719005c37f13c017","contract":["metrics.GetOrRegisterHistogram registers a new Histogram in a custom Registry when the name is not present","metrics.GetOrRegisterHistogram retrieves an existing registered Histogram without replacing it","metrics.GetOrRegisterHistogram defaults to metrics.DefaultRegistry when registry argument is nil","Histogram obtained via GetOrRegisterHistogram tracks samples and calculates statistical metrics","HistogramSnapshot taken from GetOrRegisterHistogram is read-only and panics on Clear or Update"],"goal":"verify metrics.GetOrRegisterHistogram in 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,"symbols":["metrics.GetOrRegisterHistogram"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","packageManagerVersion":"1.26.6","runtime":"go","runtimeVersion":"1.26.6","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.GetOrRegisterHistogram"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.24

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() {
	registry := metrics.NewRegistry()
	sample := metrics.NewUniformSample(100)

	// Register or get histogram
	histogram := metrics.GetOrRegisterHistogram("request_duration", registry, sample)

	// Record sample data
	histogram.Update(42)
	histogram.Update(84)
	histogram.Update(126)

	// Retrieve same histogram
	retrieved := metrics.GetOrRegisterHistogram("request_duration", registry, metrics.NewUniformSample(50))

	fmt.Printf("Count: %d\n", retrieved.Count())
	fmt.Printf("Min: %d\n", retrieved.Min())
	fmt.Printf("Max: %d\n", retrieved.Max())
	fmt.Printf("Mean: %.2f\n", retrieved.Mean())
	fmt.Printf("Median: %.2f\n", retrieved.Percentile(0.5))
}

{
  "schemaVersion": 1,
  "goal": "verify metrics.GetOrRegisterHistogram in 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"
  ],
  "symbols": [
    "metrics.GetOrRegisterHistogram"
  ]
}

package main

import (
	"fmt"
	"math"
	"os"

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

func main() {
	// Assertion 1: metrics.GetOrRegisterHistogram registers a new Histogram in a custom Registry when the name is not present
	reg := metrics.NewRegistry()
	s := metrics.NewUniformSample(100)
	h := metrics.GetOrRegisterHistogram("latency", reg, s)
	if h == nil {
		fmt.Fprintln(os.Stderr, "FAIL: GetOrRegisterHistogram returned nil")
		os.Exit(1)
	}
	if h.Sample() == nil {
		fmt.Fprintln(os.Stderr, "FAIL: h.Sample() is nil")
		os.Exit(1)
	}
	if h.Count() != 0 {
		fmt.Fprintf(os.Stderr, "FAIL: expected initial count 0, got %d\n", h.Count())
		os.Exit(1)
	}
	if reg.Get("latency") == nil {
		fmt.Fprintln(os.Stderr, "FAIL: latency metric not found in registry")
		os.Exit(1)
	}

	// Assertion 2: metrics.GetOrRegisterHistogram retrieves an existing registered Histogram without replacing it
	h.Update(100)
	if h.Count() != 1 {
		fmt.Fprintf(os.Stderr, "FAIL: expected count 1 after update, got %d\n", h.Count())
		os.Exit(1)
	}

	s2 := metrics.NewUniformSample(50)
	h2 := metrics.GetOrRegisterHistogram("latency", reg, s2)
	if h2 == nil {
		fmt.Fprintln(os.Stderr, "FAIL: second GetOrRegisterHistogram returned nil")
		os.Exit(1)
	}
	if h2.Count() != 1 || h2.Max() != 100 {
		fmt.Fprintf(os.Stderr, "FAIL: retrieved histogram does not retain existing state: count=%d, max=%d\n", h2.Count(), h2.Max())
		os.Exit(1)
	}
	h2.Update(200)
	if h.Count() != 2 || h.Max() != 200 {
		fmt.Fprintf(os.Stderr, "FAIL: updates via retrieved reference not reflected: count=%d, max=%d\n", h.Count(), h.Max())
		os.Exit(1)
	}

	// Assertion 3: metrics.GetOrRegisterHistogram defaults to metrics.DefaultRegistry when registry argument is nil
	metrics.DefaultRegistry.Unregister("default_reg_hist")
	hd := metrics.GetOrRegisterHistogram("default_reg_hist", nil, metrics.NewUniformSample(100))
	if hd == nil {
		fmt.Fprintln(os.Stderr, "FAIL: GetOrRegisterHistogram with nil registry returned nil")
		os.Exit(1)
	}
	if metrics.DefaultRegistry.Get("default_reg_hist") == nil {
		fmt.Fprintln(os.Stderr, "FAIL: metric not registered in DefaultRegistry")
		os.Exit(1)
	}
	hd.Update(50)
	hd2 := metrics.GetOrRegisterHistogram("default_reg_hist", nil, metrics.NewUniformSample(10))
	if hd2.Count() != 1 || hd2.Max() != 50 {
		fmt.Fprintf(os.Stderr, "FAIL: DefaultRegistry retrieval failed: count=%d, max=%d\n", hd2.Count(), hd2.Max())
		os.Exit(1)
	}
	metrics.DefaultRegistry.Unregister("default_reg_hist")

	// Assertion 4: Histogram obtained via GetOrRegisterHistogram tracks samples and calculates statistical metrics
	regStat := metrics.NewRegistry()
	hStat := metrics.GetOrRegisterHistogram("stats_test", regStat, metrics.NewUniformSample(100))
	values := []int64{10, 20, 30, 40, 50}
	for _, v := range values {
		hStat.Update(v)
	}
	if hStat.Count() != 5 {
		fmt.Fprintf(os.Stderr, "FAIL: expected Count 5, got %d\n", hStat.Count())
		os.Exit(1)
	}
	if hStat.Min() != 10 {
		fmt.Fprintf(os.Stderr, "FAIL: expected Min 10, got %d\n", hStat.Min())
		os.Exit(1)
	}
	if hStat.Max() != 50 {
		fmt.Fprintf(os.Stderr, "FAIL: expected Max 50, got %d\n", hStat.Max())
		os.Exit(1)
	}
	if hStat.Sum() != 150 {
		fmt.Fprintf(os.Stderr, "FAIL: expected Sum 150, got %d\n", hStat.Sum())
		os.Exit(1)
	}
	if math.Abs(hStat.Mean()-30.0) > 1e-9 {
		fmt.Fprintf(os.Stderr, "FAIL: expected Mean 30.0, got %f\n", hStat.Mean())
		os.Exit(1)
	}
	if math.Abs(hStat.Percentile(0.5)-30.0) > 1e-9 {
		fmt.Fprintf(os.Stderr, "FAIL: expected Percentile(0.5) 30.0, got %f\n", hStat.Percentile(0.5))
		os.Exit(1)
	}

	// Assertion 5: HistogramSnapshot taken from GetOrRegisterHistogram is read-only and panics on Clear or Update
	snap := hStat.Snapshot()
	if snap.Count() != 5 || snap.Min() != 10 || snap.Max() != 50 || snap.Sum() != 150 {
		fmt.Fprintf(os.Stderr, "FAIL: snapshot does not match histogram statistics\n")
		os.Exit(1)
	}

	var updatePanicked bool
	func() {
		defer func() {
			if r := recover(); r != nil {
				updatePanicked = true
			}
		}()
		snap.Update(60)
	}()
	if !updatePanicked {
		fmt.Fprintln(os.Stderr, "FAIL: HistogramSnapshot.Update did not panic")
		os.Exit(1)
	}

	var clearPanicked bool
	func() {
		defer func() {
			if r := recover(); r != nil {
				clearPanicked = true
			}
		}()
		snap.Clear()
	}()
	if !clearPanicked {
		fmt.Fprintln(os.Stderr, "FAIL: HistogramSnapshot.Clear did not panic")
		os.Exit(1)
	}

	fmt.Println("All contract assertions passed successfully.")
}