goodhistogram: add HistogramVec for labeled histogram collection

Add HistogramVec, a label-partitioned collection of Histograms that
implements prometheus.Collector. WithLabelValues returns a *Histogram
for direct int64 recording on the hot path; the vec handles Prometheus
registration and scrape-time export with label pairs.

Co-Authored-By: roachdev-claude <roachdev-claude-bot@cockroachlabs.com>

Author: angles-n-daemons

README.md

@@ -100,6 +100,24 @@ sparse fields (schema, spans, deltas). Because the internal bucket
 indices are Prometheus bucket keys by construction, export is a direct
 copy with no remapping.
 
+### Labeled histograms (HistogramVec)
+
+For multi-dimensional histograms partitioned by label values, use
+`HistogramVec`. It implements `prometheus.Collector` so the entire
+vec can be registered with a registry.
+
+```go
+vec := goodhistogram.NewHistogramVec(
+    goodhistogram.Params{Lo: 500, Hi: 60e9, ErrorBound: 0.10},
+    "request_duration_ns", "Request duration in nanoseconds",
+    []string{"method", "path"},
+)
+prometheus.MustRegister(vec)
+
+// Hot path — WithLabelValues returns a *Histogram for direct recording.
+vec.WithLabelValues("GET", "/api").Record(durationNs)
+```
+
 ### Export to Prometheus proto
 
 If you need the proto directly (e.g. for remote write or custom

vec.go

@@ -0,0 +1,141 @@
+// Copyright 2026 The Cockroach Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+package goodhistogram
+
+import (
+	"fmt"
+	"strings"
+	"sync"
+
+	"github.com/prometheus/client_golang/prometheus"
+	prometheusgo "github.com/prometheus/client_model/go"
+)
+
+// HistogramVec is a collection of Histograms partitioned by label values.
+// It implements prometheus.Collector so the entire vec can be registered
+// with a Prometheus registry. Recording is done on the individual
+// *Histogram returned by WithLabelValues.
+type HistogramVec struct {
+	params     Params
+	desc       *prometheus.Desc
+	labelNames []string
+
+	mu         sync.RWMutex
+	histograms map[string]*labeledHistogram
+}
+
+type labeledHistogram struct {
+	h          *Histogram
+	labelPairs []*prometheusgo.LabelPair
+}
+
+// NewHistogramVec creates a new HistogramVec. All child histograms share the
+// same Params. The desc is created internally from name, help, and labelNames.
+func NewHistogramVec(p Params, name, help string, labelNames []string) *HistogramVec {
+	return &HistogramVec{
+		params:     p,
+		desc:       prometheus.NewDesc(name, help, labelNames, nil),
+		labelNames: labelNames,
+		histograms: make(map[string]*labeledHistogram),
+	}
+}
+
+// WithLabelValues returns the Histogram for the given label values,
+// creating it if it doesn't exist. Panics if the number of values
+// doesn't match the number of label names.
+func (v *HistogramVec) WithLabelValues(lvs ...string) *Histogram {
+	if len(lvs) != len(v.labelNames) {
+		panic(fmt.Sprintf(
+			"goodhistogram: expected %d label values, got %d",
+			len(v.labelNames), len(lvs),
+		))
+	}
+	key := strings.Join(lvs, "\x00")
+
+	v.mu.RLock()
+	if lh, ok := v.histograms[key]; ok {
+		v.mu.RUnlock()
+		return lh.h
+	}
+	v.mu.RUnlock()
+
+	v.mu.Lock()
+	defer v.mu.Unlock()
+	if lh, ok := v.histograms[key]; ok {
+		return lh.h
+	}
+	h := New(v.params)
+	v.histograms[key] = &labeledHistogram{
+		h:          h,
+		labelPairs: makeLabelPairs(v.labelNames, lvs),
+	}
+	return h
+}
+
+// DeleteLabelValues removes the Histogram for the given label values.
+// Returns true if the entry existed.
+func (v *HistogramVec) DeleteLabelValues(lvs ...string) bool {
+	key := strings.Join(lvs, "\x00")
+	v.mu.Lock()
+	defer v.mu.Unlock()
+	_, ok := v.histograms[key]
+	delete(v.histograms, key)
+	return ok
+}
+
+// Reset removes all child histograms.
+func (v *HistogramVec) Reset() {
+	v.mu.Lock()
+	defer v.mu.Unlock()
+	v.histograms = make(map[string]*labeledHistogram)
+}
+
+// Describe implements prometheus.Collector.
+func (v *HistogramVec) Describe(ch chan<- *prometheus.Desc) {
+	ch <- v.desc
+}
+
+// Collect implements prometheus.Collector.
+func (v *HistogramVec) Collect(ch chan<- prometheus.Metric) {
+	v.mu.RLock()
+	defer v.mu.RUnlock()
+	for _, lh := range v.histograms {
+		ch <- &histogramMetric{
+			desc:       v.desc,
+			h:          lh.h,
+			labelPairs: lh.labelPairs,
+		}
+	}
+}
+
+// histogramMetric implements prometheus.Metric for a single labeled histogram.
+type histogramMetric struct {
+	desc       *prometheus.Desc
+	h          *Histogram
+	labelPairs []*prometheusgo.LabelPair
+}
+
+func (m *histogramMetric) Desc() *prometheus.Desc { return m.desc }
+
+func (m *histogramMetric) Write(out *prometheusgo.Metric) error {
+	snap := m.h.Snapshot()
+	out.Histogram = snap.ToPrometheusHistogram()
+	out.Label = m.labelPairs
+	return nil
+}
+
+func makeLabelPairs(names, values []string) []*prometheusgo.LabelPair {
+	pairs := make([]*prometheusgo.LabelPair, len(names))
+	for i := range names {
+		n := names[i]
+		v := values[i]
+		pairs[i] = &prometheusgo.LabelPair{Name: &n, Value: &v}
+	}
+	return pairs
+}

vec_test.go

@@ -0,0 +1,130 @@
+// Copyright 2026 The Cockroach Authors.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+package goodhistogram
+
+import (
+	"sort"
+	"sync"
+	"testing"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/stretchr/testify/require"
+)
+
+func TestHistogramVecGather(t *testing.T) {
+	vec := NewHistogramVec(
+		Params{Lo: 100, Hi: 1e9},
+		"request_duration_ns", "Request duration", []string{"method", "path"},
+	)
+	reg := prometheus.NewRegistry()
+	require.NoError(t, reg.Register(vec))
+
+	vec.WithLabelValues("GET", "/api").Record(1000)
+	vec.WithLabelValues("GET", "/api").Record(2000)
+	vec.WithLabelValues("POST", "/api").Record(5000)
+
+	families, err := reg.Gather()
+	require.NoError(t, err)
+	require.Len(t, families, 1)
+	require.Equal(t, "request_duration_ns", *families[0].Name)
+
+	metrics := families[0].Metric
+	require.Len(t, metrics, 2)
+
+	// Sort by first label value for deterministic assertions.
+	sort.Slice(metrics, func(i, j int) bool {
+		return *metrics[i].Label[0].Value < *metrics[j].Label[0].Value
+	})
+
+	// GET /api: 2 observations, sum = 3000
+	require.Equal(t, "method", *metrics[0].Label[0].Name)
+	require.Equal(t, "GET", *metrics[0].Label[0].Value)
+	require.Equal(t, uint64(2), *metrics[0].Histogram.SampleCount)
+	require.Equal(t, float64(3000), *metrics[0].Histogram.SampleSum)
+
+	// POST /api: 1 observation, sum = 5000
+	require.Equal(t, "POST", *metrics[1].Label[0].Value)
+	require.Equal(t, uint64(1), *metrics[1].Histogram.SampleCount)
+	require.Equal(t, float64(5000), *metrics[1].Histogram.SampleSum)
+}
+
+func TestHistogramVecSamePointer(t *testing.T) {
+	vec := NewHistogramVec(
+		Params{Lo: 100, Hi: 1e9},
+		"test", "test", []string{"x"},
+	)
+	h1 := vec.WithLabelValues("a")
+	h2 := vec.WithLabelValues("a")
+	require.True(t, h1 == h2, "WithLabelValues should return the same *Histogram")
+}
+
+func TestHistogramVecWrongLabelCountPanics(t *testing.T) {
+	vec := NewHistogramVec(
+		Params{Lo: 100, Hi: 1e9},
+		"test", "test", []string{"method", "path"},
+	)
+	require.Panics(t, func() { vec.WithLabelValues("GET") })
+}
+
+func TestHistogramVecDeleteAndReset(t *testing.T) {
+	vec := NewHistogramVec(
+		Params{Lo: 100, Hi: 1e9},
+		"test", "test", []string{"x"},
+	)
+	reg := prometheus.NewRegistry()
+	require.NoError(t, reg.Register(vec))
+
+	vec.WithLabelValues("a").Record(100)
+	vec.WithLabelValues("b").Record(200)
+
+	require.True(t, vec.DeleteLabelValues("a"))
+	require.False(t, vec.DeleteLabelValues("a"))
+
+	families, err := reg.Gather()
+	require.NoError(t, err)
+	require.Len(t, families[0].Metric, 1)
+	require.Equal(t, "b", *families[0].Metric[0].Label[0].Value)
+
+	vec.Reset()
+	families, err = reg.Gather()
+	require.NoError(t, err)
+	require.Empty(t, families)
+}
+
+func TestHistogramVecConcurrent(t *testing.T) {
+	vec := NewHistogramVec(
+		Params{Lo: 100, Hi: 1e9},
+		"test", "test", []string{"x"},
+	)
+
+	var wg sync.WaitGroup
+	labels := []string{"a", "b", "c", "d"}
+	for _, l := range labels {
+		for g := 0; g < 10; g++ {
+			wg.Add(1)
+			go func(label string) {
+				defer wg.Done()
+				h := vec.WithLabelValues(label)
+				for i := 0; i < 1000; i++ {
+					h.Record(500)
+				}
+			}(l)
+		}
+	}
+	wg.Wait()
+
+	reg := prometheus.NewRegistry()
+	require.NoError(t, reg.Register(vec))
+	families, err := reg.Gather()
+	require.NoError(t, err)
+	require.Len(t, families[0].Metric, 4)
+	for _, m := range families[0].Metric {
+		require.Equal(t, uint64(10000), *m.Histogram.SampleCount)
+	}
+}