github.com/prometheus/client_golang v1.19.1: prometheus.Histogram

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 github.com/prometheus/client_golang/prometheus.Histogram in pkg:golang/github.com/prometheus/client_golang@v1.19.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/prometheus/client_golang@v1.19.1
Demonstrate these symbols/APIs:
  - github.com/prometheus/client_golang/prometheus.Histogram
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:5c85978c9fea6bf455d46ce0efa19511fa90571b99eaa19ebe90afa9faaf886e","contract":["prometheus.NewHistogram creates a Histogram metric with specified name and help string, defaulting to prometheus.DefBuckets when Buckets option is omitted.","Histogram.Observe records observations, accumulating total sample count and sample sum across all calls.","Histogram.Observe increments cumulative bucket counts for all configured upper bounds greater than or equal to the observed value.","prometheus.LinearBuckets and prometheus.ExponentialBuckets generate expected slice bounds for histogram bucket configuration.","Histogram registers with prometheus.Registry and gathers into a dto.MetricFamily of type MetricType_HISTOGRAM containing sample count and bucket distributions."],"goal":"verify github.com/prometheus/client_golang/prometheus.Histogram in pkg:golang/github.com/prometheus/client_golang@v1.19.1","kind":"HOW","packages":["pkg:golang/github.com/prometheus/client_golang@v1.19.1"],"schemaVersion":1,"symbols":["github.com/prometheus/client_golang/prometheus.Histogram"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","executionContext":"go","language":"go","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/prometheus/client_golang@v1.19.1"],"schemaVersion":1,"subject":"pkg:golang/github.com/prometheus/client_golang@v1.19.1","symbols":["github.com/prometheus/client_golang/prometheus.Histogram"],"verifierAdapter":"golang@1"}

module example.com/histogram

go 1.26.6

require (
	github.com/prometheus/client_golang v1.19.1
	github.com/prometheus/client_model v0.5.0
)

require (
	github.com/beorn7/perks v1.0.1 // indirect
	github.com/cespare/xxhash/v2 v2.2.0 // indirect
	github.com/prometheus/common v0.48.0 // indirect
	github.com/prometheus/procfs v0.12.0 // indirect
	golang.org/x/sys v0.17.0 // indirect
	google.golang.org/protobuf v1.33.0 // indirect
)

github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
github.com/cespare/xxhash/v2 v2.2.0 h1:DC2CZ1Ep5Y4k3ZQ899DldepgrayRUGE6BBZ/cd9Cj44=
github.com/cespare/xxhash/v2 v2.2.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/prometheus/client_golang v1.19.1 h1:wZWJDwK+NameRJuPGDhlnFgx8e8HN3XHQeLaYJFJBOE=
github.com/prometheus/client_golang v1.19.1/go.mod h1:mP78NwGzrVks5S2H6ab8+ZZGJLZUq1hoULYBAYBw1Ho=
github.com/prometheus/client_model v0.5.0 h1:VQw1hfvPvk3Uv6Qf29VrPF32JB6rtbgI6cYPYQjL0Qw=
github.com/prometheus/client_model v0.5.0/go.mod h1:dTiFglRmd66nLR9Pv9f0mZi7B7fk5Pm3gvsjB5tr+kI=
github.com/prometheus/common v0.48.0 h1:QO8U2CdOzSn1BBsmXJXduaaW+dY/5QLjfB8svtSzKKE=
github.com/prometheus/common v0.48.0/go.mod h1:0/KsvlIEfPQCQ5I2iNSAWKPZziNCvRs5EC6ILDTlAPc=
github.com/prometheus/procfs v0.12.0 h1:jluTpSng7V9hY0O2R9DzzJHYb2xULk9VTR1V1R/k6Bo=
github.com/prometheus/procfs v0.12.0/go.mod h1:pcuDEFsWDnvcgNzo4EEweacyhjeA9Zk3cnaOZAZEfOo=
golang.org/x/sys v0.17.0 h1:25cE3gD+tdBA7lp7QfhuV+rJiE9YXTcS3VG1SqssI/Y=
golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
google.golang.org/protobuf v1.33.0 h1:uNO2rsAINq/JlFpSdYEKIZ0uKD/R9cpdv0T+yoGwGmI=
google.golang.org/protobuf v1.33.0/go.mod h1:c6P6GXX6sHbq/GpV6MGZEdwhWPcYBgnhAHhKbcUYpos=

package main

import (
	"fmt"

	"github.com/prometheus/client_golang/prometheus"
	dto "github.com/prometheus/client_model/go"
)

func main() {
	hist := prometheus.NewHistogram(prometheus.HistogramOpts{
		Name:    "http_request_duration_seconds",
		Help:    "Duration of HTTP requests in seconds.",
		Buckets: []float64{0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0},
	})

	hist.Observe(0.08)
	hist.Observe(0.22)
	hist.Observe(1.5)

	metric := &dto.Metric{}
	if err := hist.Write(metric); err != nil {
		panic(err)
	}

	h := metric.GetHistogram()
	fmt.Printf("Sample Count: %d\n", h.GetSampleCount())
	fmt.Printf("Sample Sum: %.2f\n", h.GetSampleSum())
	for _, b := range h.GetBucket() {
		fmt.Printf("Bucket <= %.2f: count %d\n", b.GetUpperBound(), b.GetCumulativeCount())
	}
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/prometheus/client_golang/prometheus.Histogram in pkg:golang/github.com/prometheus/client_golang@v1.19.1",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/prometheus/client_golang@v1.19.1"
  ],
  "symbols": [
    "github.com/prometheus/client_golang/prometheus.Histogram"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

package test

import (
	"math"
	"testing"

	"github.com/prometheus/client_golang/prometheus"
	dto "github.com/prometheus/client_model/go"
)

func TestHistogramCreationAndDefaultBuckets(t *testing.T) {
	hist := prometheus.NewHistogram(prometheus.HistogramOpts{
		Name: "test_default_hist",
		Help: "Histogram with default buckets",
	})

	if hist == nil {
		t.Fatal("expected non-nil Histogram instance")
	}

	metric := &dto.Metric{}
	if err := hist.Write(metric); err != nil {
		t.Fatalf("hist.Write failed: %v", err)
	}

	h := metric.GetHistogram()
	if h == nil {
		t.Fatal("metric.GetHistogram() returned nil")
	}

	if len(h.GetBucket()) != len(prometheus.DefBuckets) {
		t.Errorf("got %d buckets, expected default bucket count %d", len(h.GetBucket()), len(prometheus.DefBuckets))
	}
}

func TestHistogramObserveAndAccumulation(t *testing.T) {
	buckets := []float64{0.1, 0.5, 1.0, 5.0}
	hist := prometheus.NewHistogram(prometheus.HistogramOpts{
		Name:    "request_duration_seconds",
		Help:    "Request duration in seconds",
		Buckets: buckets,
	})

	observations := []float64{0.05, 0.2, 0.5, 0.8, 1.5, 6.0}
	for _, val := range observations {
		hist.Observe(val)
	}

	metric := &dto.Metric{}
	if err := hist.Write(metric); err != nil {
		t.Fatalf("hist.Write failed: %v", err)
	}

	h := metric.GetHistogram()
	if got := h.GetSampleCount(); got != uint64(len(observations)) {
		t.Errorf("sample count = %d, want %d", got, len(observations))
	}

	var expectedSum float64
	for _, v := range observations {
		expectedSum += v
	}
	if math.Abs(h.GetSampleSum()-expectedSum) > 1e-9 {
		t.Errorf("sample sum = %f, want %f", h.GetSampleSum(), expectedSum)
	}

	expectedCumulative := []uint64{
		1, // <= 0.1: 0.05
		3, // <= 0.5: 0.05, 0.2, 0.5
		4, // <= 1.0: 0.05, 0.2, 0.5, 0.8
		5, // <= 5.0: 0.05, 0.2, 0.5, 0.8, 1.5
	}

	pbBuckets := h.GetBucket()
	if len(pbBuckets) != len(buckets) {
		t.Fatalf("got %d buckets, want %d", len(pbBuckets), len(buckets))
	}

	for i, b := range pbBuckets {
		if b.GetUpperBound() != buckets[i] {
			t.Errorf("bucket[%d] upper bound = %f, want %f", i, b.GetUpperBound(), buckets[i])
		}
		if b.GetCumulativeCount() != expectedCumulative[i] {
			t.Errorf("bucket[%d] (<= %f) cumulative count = %d, want %d", i, b.GetUpperBound(), b.GetCumulativeCount(), expectedCumulative[i])
		}
	}
}

func TestHistogramBucketGenerators(t *testing.T) {
	linear := prometheus.LinearBuckets(1.0, 2.0, 4)
	expectedLinear := []float64{1.0, 3.0, 5.0, 7.0}
	if len(linear) != len(expectedLinear) {
		t.Fatalf("LinearBuckets length = %d, want %d", len(linear), len(expectedLinear))
	}
	for i, v := range linear {
		if math.Abs(v-expectedLinear[i]) > 1e-9 {
			t.Errorf("LinearBuckets[%d] = %f, want %f", i, v, expectedLinear[i])
		}
	}

	exponential := prometheus.ExponentialBuckets(1.0, 2.0, 4)
	expectedExp := []float64{1.0, 2.0, 4.0, 8.0}
	if len(exponential) != len(expectedExp) {
		t.Fatalf("ExponentialBuckets length = %d, want %d", len(exponential), len(expectedExp))
	}
	for i, v := range exponential {
		if math.Abs(v-expectedExp[i]) > 1e-9 {
			t.Errorf("ExponentialBuckets[%d] = %f, want %f", i, v, expectedExp[i])
		}
	}
}

func TestHistogramRegistryCollection(t *testing.T) {
	registry := prometheus.NewRegistry()
	hist := prometheus.NewHistogram(prometheus.HistogramOpts{
		Name:    "custom_metric_seconds",
		Help:    "Custom metric help",
		Buckets: []float64{1.0, 5.0},
	})

	if err := registry.Register(hist); err != nil {
		t.Fatalf("failed to register histogram: %v", err)
	}

	hist.Observe(2.5)

	metricFamilies, err := registry.Gather()
	if err != nil {
		t.Fatalf("registry.Gather failed: %v", err)
	}

	if len(metricFamilies) != 1 {
		t.Fatalf("gathered %d metric families, want 1", len(metricFamilies))
	}

	mf := metricFamilies[0]
	if mf.GetName() != "custom_metric_seconds" {
		t.Errorf("metric family name = %q, want %q", mf.GetName(), "custom_metric_seconds")
	}
	if mf.GetType() != dto.MetricType_HISTOGRAM {
		t.Errorf("metric type = %v, want %v", mf.GetType(), dto.MetricType_HISTOGRAM)
	}

	metrics := mf.GetMetric()
	if len(metrics) != 1 {
		t.Fatalf("metric count = %d, want 1", len(metrics))
	}
	h := metrics[0].GetHistogram()
	if h.GetSampleCount() != 1 {
		t.Errorf("sample count = %d, want 1", h.GetSampleCount())
	}
}