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

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.NewUniformSample 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.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:cc5a2347a07f06dbd6fe2ea505a9a59ae6ae59a396982bddf9d92a3ee07cc70a","contract":["metrics.NewUniformSample constructs a new uniform sample with the given reservoir capacity","UniformSample.Update records sample values and updates count, size, min, max, sum, and variance","UniformSample maintains a bounded reservoir size when updating past capacity","UniformSample.Percentile and Percentiles calculate statistical distribution percentiles","UniformSample.Snapshot returns an immutable point-in-time copy of the sample","UniformSample.Clear resets recorded values and statistics"],"goal":"verify metrics.NewUniformSample 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.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.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() {
	sample := metrics.NewUniformSample(50)

	for i := int64(1); i <= 100; i++ {
		sample.Update(i)
	}

	snap := sample.Snapshot()
	fmt.Printf("Count: %d, Sample size: %d, Mean: %.2f, 95th percentile: %.2f\n",
		snap.Count(), snap.Size(), snap.Mean(), snap.Percentile(0.95))
}

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

package main

import (
	"fmt"
	"math"
	"os"

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

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

	// 2. UniformSample.Update records sample values and updates count, size, min, max, sum, and variance
	s.Update(10)
	s.Update(20)
	s.Update(30)
	if s.Count() != 3 {
		fmt.Fprintf(os.Stderr, "expected count 3 after updates, got %d\n", s.Count())
		os.Exit(1)
	}
	if s.Size() != 3 {
		fmt.Fprintf(os.Stderr, "expected size 3 after updates, got %d\n", s.Size())
		os.Exit(1)
	}
	if s.Min() != 10 {
		fmt.Fprintf(os.Stderr, "expected min 10, got %d\n", s.Min())
		os.Exit(1)
	}
	if s.Max() != 30 {
		fmt.Fprintf(os.Stderr, "expected max 30, got %d\n", s.Max())
		os.Exit(1)
	}
	if s.Sum() != 60 {
		fmt.Fprintf(os.Stderr, "expected sum 60, got %d\n", s.Sum())
		os.Exit(1)
	}
	if math.Abs(s.Mean()-20.0) > 0.001 {
		fmt.Fprintf(os.Stderr, "expected mean 20.0, got %f\n", s.Mean())
		os.Exit(1)
	}
	if s.Variance() <= 0.0 || s.StdDev() <= 0.0 {
		fmt.Fprintf(os.Stderr, "expected positive variance and stddev, got var=%f stddev=%f\n", s.Variance(), s.StdDev())
		os.Exit(1)
	}

	// 3. UniformSample maintains a bounded reservoir size when updating past capacity
	for i := int64(31); i <= 100; i++ {
		s.Update(i)
	}
	if s.Count() != 73 {
		fmt.Fprintf(os.Stderr, "expected count 73, got %d\n", s.Count())
		os.Exit(1)
	}
	if s.Size() != 50 {
		fmt.Fprintf(os.Stderr, "expected bounded reservoir size 50, got %d\n", s.Size())
		os.Exit(1)
	}
	if len(s.Values()) != 50 {
		fmt.Fprintf(os.Stderr, "expected exactly 50 sampled values, got %d\n", len(s.Values()))
		os.Exit(1)
	}

	// 4. UniformSample.Percentile and Percentiles calculate statistical distribution percentiles
	p50 := s.Percentile(0.50)
	p95 := s.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 := s.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. UniformSample.Snapshot returns an immutable point-in-time copy of the sample
	snap := s.Snapshot()
	if snap == nil {
		fmt.Fprintf(os.Stderr, "Snapshot returned nil\n")
		os.Exit(1)
	}
	if snap.Count() != s.Count() {
		fmt.Fprintf(os.Stderr, "expected snapshot count %d, got %d\n", s.Count(), snap.Count())
		os.Exit(1)
	}
	if snap.Size() != s.Size() {
		fmt.Fprintf(os.Stderr, "expected snapshot size %d, got %d\n", s.Size(), snap.Size())
		os.Exit(1)
	}
	prevCount := snap.Count()
	s.Update(1000)
	if snap.Count() != prevCount {
		fmt.Fprintf(os.Stderr, "expected snapshot count to remain %d, got %d\n", prevCount, 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 immutable snapshot\n")
		os.Exit(1)
	}

	// 6. UniformSample.Clear resets recorded values and statistics
	s.Clear()
	if s.Count() != 0 || s.Size() != 0 || s.Min() != 0 || s.Max() != 0 || s.Sum() != 0 {
		fmt.Fprintf(os.Stderr, "expected cleared sample to have zero count/size/min/max/sum, got count=%d size=%d min=%d max=%d sum=%d\n",
			s.Count(), s.Size(), s.Min(), s.Max(), s.Sum())
		os.Exit(1)
	}
	if len(s.Values()) != 0 {
		fmt.Fprintf(os.Stderr, "expected empty values after Clear, got %d\n", len(s.Values()))
		os.Exit(1)
	}

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