puma-plus-core 0.1.0

data/go/internal/metrics/endpoints.go

@@ -0,0 +1,244 @@
+package metrics
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+)
+
+// Source supplies the live queue state the endpoints report alongside timings.
+// Implemented by queue.Registry; an interface here keeps metrics from importing
+// queue and creating a cycle.
+type Source interface {
+	Depth() int    // requests waiting for capacity (L)
+	Busy() int     // connections currently serving (b)
+	Capacity() int // total connected worker threads (c)
+	Idle() int     // connections available right now
+}
+
+// Stats is the /stats payload.
+//
+// The top-level fields are a strict superset of puma's stats shape
+// (lib/puma/thread_pool.rb:143, docs/stats.md) with the same names and
+// semantics, so pumactl-style tooling, existing Grafana dashboards and APM
+// integrations keep working against puma-plus unmodified. Everything genuinely
+// new lives under `queue`, where nothing can collide.
+type Stats struct {
+	// --- puma-compatible surface ---
+	Backlog       int    `json:"backlog"`
+	Running       int    `json:"running"`
+	PoolCapacity  int    `json:"pool_capacity"`
+	BusyThreads   int    `json:"busy_threads"`
+	MaxThreads    int    `json:"max_threads"`
+	RequestsCount uint64 `json:"requests_count"`
+	StartedAt     string `json:"started_at"`
+
+	// --- what puma cannot report ---
+	Queue QueueStats `json:"queue"`
+
+	Versions map[string]string `json:"versions"`
+}
+
+// QueueStats is the queue-time view. Puma has no equivalent: it exposes no
+// latency metric of any kind, and its queue depth is sampled from workers every
+// worker_check_interval (default 5s) rather than read directly.
+type QueueStats struct {
+	// Percentiles over the scaling window, in milliseconds.
+	P50Ms float64 `json:"p50_ms"`
+	P95Ms float64 `json:"p95_ms"`
+	P99Ms float64 `json:"p99_ms"`
+	MaxMs float64 `json:"max_ms"`
+
+	// Depth is L, exact and instantaneous rather than sampled.
+	Depth int `json:"depth"`
+
+	// PredictedWaitMs is Little's Law applied to the next arrival. Leading
+	// indicator; the percentiles above are lagging.
+	PredictedWaitMs float64 `json:"predicted_wait_ms"`
+
+	ArrivalRate  float64 `json:"arrival_rate"`
+	ServiceMeanS float64 `json:"service_mean_s"`
+	Utilization  float64 `json:"utilization"`
+
+	ShedCount  uint64 `json:"shed_count"`
+	ErrorCount uint64 `json:"error_count"`
+
+	// GVLFraction is the share of service time spent queued behind the GVL.
+	// Puma has no equivalent, and neither does any Ruby server: it needs the
+	// internal thread event hook.
+	GVLFraction float64 `json:"gvl_fraction"`
+	CPUFraction float64 `json:"cpu_fraction"`
+
+	ServiceP50Ms float64 `json:"service_p50_ms"`
+	ServiceP95Ms float64 `json:"service_p95_ms"`
+	TTFBP50Ms    float64 `json:"ttfb_p50_ms"`
+	TTFBP95Ms    float64 `json:"ttfb_p95_ms"`
+	TTFBP99Ms    float64 `json:"ttfb_p99_ms"`
+}
+
+// Snapshot builds the current stats.
+func (c *Collector) Snapshot(src Source, maxThreads int) Stats {
+	qp50, qp95, qp99 := c.QuantilesNs(c.QueueTime, ScaleWindow)
+	sp50, sp95, _ := c.QuantilesNs(c.ServiceTime, ScaleWindow)
+	tp50, tp95, tp99 := c.QuantilesNs(c.TTFB, ScaleWindow)
+
+	depth, capacity := src.Depth(), src.Capacity()
+	arrival := c.ArrivalSlow.Value()
+	service := c.ServiceSlow.Value()
+
+	utilization := 0.0
+	if capacity > 0 {
+		utilization = arrival * service / float64(capacity)
+	}
+
+	return Stats{
+		Backlog: depth,
+		Running: capacity,
+		// puma defines pool_capacity as spare capacity: idle threads plus
+		// unspawned headroom. With connection-per-thread, idle conns are exactly
+		// that.
+		PoolCapacity: src.Idle(),
+		// puma's busy_threads is spawned - waiting + todo, i.e. in-flight work
+		// including what is queued. Same meaning here.
+		BusyThreads:   src.Busy() + depth,
+		MaxThreads:    maxThreads,
+		RequestsCount: c.RequestsCount.Load(),
+		StartedAt:     c.startedAt.UTC().Format(time.RFC3339),
+		Queue: QueueStats{
+			P50Ms:           msFromNs(qp50),
+			P95Ms:           msFromNs(qp95),
+			P99Ms:           msFromNs(qp99),
+			MaxMs:           msFromNs(c.QueueTime.Lifetime().Max()),
+			Depth:           depth,
+			PredictedWaitMs: float64(c.PredictedWait(depth, capacity).Nanoseconds()) / 1e6,
+			ArrivalRate:     arrival,
+			ServiceMeanS:    service,
+			Utilization:     utilization,
+			GVLFraction:     gvlOf(c),
+			CPUFraction:     c.CPUFraction.Value(),
+			ShedCount:       c.ShedCount.Load(),
+			ErrorCount:      c.ErrorCount.Load(),
+			ServiceP50Ms:    msFromNs(sp50),
+			ServiceP95Ms:    msFromNs(sp95),
+			TTFBP50Ms:       msFromNs(tp50),
+			TTFBP95Ms:       msFromNs(tp95),
+			TTFBP99Ms:       msFromNs(tp99),
+		},
+		Versions: map[string]string{"puma_plus": "0.1.0-spike"},
+	}
+}
+
+func msFromNs(ns uint64) float64 { return float64(ns) / 1e6 }
+
+func gvlOf(c *Collector) float64 {
+	v, _ := c.GVL.Fraction()
+	return v
+}
+
+// Handler serves /stats and /metrics on the control listener.
+type Handler struct {
+	col        *Collector
+	src        Source
+	maxThreads int
+}
+
+// NewHandler wires a collector and queue source to the control endpoints.
+func NewHandler(col *Collector, src Source, maxThreads int) *Handler {
+	return &Handler{col: col, src: src, maxThreads: maxThreads}
+}
+
+// Mux returns the control-plane routes.
+func (h *Handler) Mux() *http.ServeMux {
+	mux := http.NewServeMux()
+	mux.HandleFunc("/stats", h.stats)
+	mux.HandleFunc("/metrics", h.prometheus)
+	mux.HandleFunc("/health", func(w http.ResponseWriter, _ *http.Request) {
+		// Healthy means at least one worker thread is connected and able to
+		// serve. Capacity is the readiness signal, so this needs no probing.
+		if h.src.Capacity() == 0 {
+			http.Error(w, "no workers connected", http.StatusServiceUnavailable)
+			return
+		}
+		fmt.Fprintln(w, "ok")
+	})
+	return mux
+}
+
+func (h *Handler) stats(w http.ResponseWriter, r *http.Request) {
+	s := h.col.Snapshot(h.src, h.maxThreads)
+	w.Header().Set("Content-Type", "application/json")
+	enc := json.NewEncoder(w)
+	if r.URL.Query().Get("pretty") != "" {
+		enc.SetIndent("", "  ")
+	}
+	_ = enc.Encode(s)
+}
+
+// prometheus renders the exposition format. The log-linear buckets export
+// directly as `le` boundaries -- no re-bucketing, no precision lost in the
+// translation, which is one of the reasons for choosing that histogram shape.
+func (h *Handler) prometheus(w http.ResponseWriter, _ *http.Request) {
+	var b strings.Builder
+	s := h.col.Snapshot(h.src, h.maxThreads)
+
+	writeHist(&b, "puma_plus_queue_time_seconds",
+		"Time a request spent runnable but unserved.", h.col.QueueTime.Lifetime())
+	writeHist(&b, "puma_plus_service_time_seconds",
+		"Time spent inside the Rack application.", h.col.ServiceTime.Lifetime())
+	writeHist(&b, "puma_plus_ttfb_seconds",
+		"Time from request runnable to response headers.", h.col.TTFB.Lifetime())
+
+	writeGauge(&b, "puma_plus_queue_depth",
+		"Requests waiting for a free worker thread.", float64(s.Backlog))
+	writeGauge(&b, "puma_plus_threads_total",
+		"Connected Ruby worker threads.", float64(s.Running))
+	writeGauge(&b, "puma_plus_threads_busy",
+		"Worker threads currently serving a request.", float64(s.BusyThreads))
+	writeGauge(&b, "puma_plus_predicted_wait_seconds",
+		"Little's Law estimate of the next arrival's queue time.",
+		s.Queue.PredictedWaitMs/1000)
+	writeGauge(&b, "puma_plus_arrival_rate",
+		"Requests per second, EWMA.", s.Queue.ArrivalRate)
+	writeGauge(&b, "puma_plus_utilization",
+		"Offered load over capacity (rho).", s.Queue.Utilization)
+	writeGauge(&b, "puma_plus_gvl_fraction",
+		"Share of available thread-time spent queued behind Ruby's GVL.", s.Queue.GVLFraction)
+	writeGauge(&b, "puma_plus_cpu_fraction",
+		"Share of service time spent on CPU.", s.Queue.CPUFraction)
+
+	writeCounter(&b, "puma_plus_requests_total",
+		"Requests completed.", float64(s.RequestsCount))
+	writeCounter(&b, "puma_plus_shed_total",
+		"Requests rejected without dispatch.", float64(s.Queue.ShedCount))
+	writeCounter(&b, "puma_plus_errors_total",
+		"Backend failures.", float64(s.Queue.ErrorCount))
+
+	w.Header().Set("Content-Type", "text/plain; version=0.0.4; charset=utf-8")
+	_, _ = w.Write([]byte(b.String()))
+}
+
+func writeHist(b *strings.Builder, name, help string, h *Histogram) {
+	fmt.Fprintf(b, "# HELP %s %s\n# TYPE %s histogram\n", name, help, name)
+	for _, bk := range h.Buckets() {
+		fmt.Fprintf(b, "%s_bucket{le=\"%s\"} %d\n",
+			name, strconv.FormatFloat(float64(bk.UpperBound)/1e9, 'g', -1, 64),
+			bk.CumulativeCount)
+	}
+	fmt.Fprintf(b, "%s_bucket{le=\"+Inf\"} %d\n", name, h.Count())
+	fmt.Fprintf(b, "%s_sum %s\n", name,
+		strconv.FormatFloat(float64(h.Sum())/1e9, 'g', -1, 64))
+	fmt.Fprintf(b, "%s_count %d\n", name, h.Count())
+}
+
+func writeGauge(b *strings.Builder, name, help string, v float64) {
+	fmt.Fprintf(b, "# HELP %s %s\n# TYPE %s gauge\n%s %s\n",
+		name, help, name, name, strconv.FormatFloat(v, 'g', -1, 64))
+}
+
+func writeCounter(b *strings.Builder, name, help string, v float64) {
+	fmt.Fprintf(b, "# HELP %s %s\n# TYPE %s counter\n%s %s\n",
+		name, help, name, name, strconv.FormatFloat(v, 'g', -1, 64))
+}

data/go/internal/metrics/gvl.go

@@ -0,0 +1,136 @@
+package metrics
+
+import (
+	"sync"
+	"time"
+)
+
+// GVLTracker turns each worker's cumulative GVL-wait counter into a fraction of
+// available thread-time.
+//
+// The counter arrives on every response; the useful quantity is a rate. For a
+// worker with T threads observed over an interval dt, the thread-time available
+// was T*dt, and the share of it spent queued behind the GVL is:
+//
+//	fraction = delta(gvl_wait_ns) / (threads * dt)
+//
+// A fraction near 1.0 means the worker's threads spend essentially all their
+// time waiting for each other -- adding another thread there lengthens the queue
+// rather than raising throughput.
+//
+// Per worker rather than globally, because the GVL is per process: two workers
+// can be in completely different regimes, and averaging them would hide both.
+type GVLTracker struct {
+	mu      sync.Mutex
+	workers map[int]*gvlWorker
+	// fraction is the most recent aggregate across workers.
+	fraction float64
+	known    bool
+}
+
+type gvlWorker struct {
+	lastCumulative uint64
+	lastSeen       time.Time
+	fraction       float64
+	haveBaseline   bool
+}
+
+// NewGVLTracker creates an empty tracker.
+func NewGVLTracker() *GVLTracker {
+	return &GVLTracker{workers: map[int]*gvlWorker{}}
+}
+
+// Observe records a worker's cumulative counter.
+//
+// threads is how many worker threads that process has connected, which is the
+// denominator: one thread cannot wait for the GVL more than 100% of the time,
+// but six threads can accumulate six seconds of waiting per wall second.
+func (g *GVLTracker) Observe(workerID int, cumulative uint64, threads int, now time.Time) {
+	if threads <= 0 {
+		return
+	}
+
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	w := g.workers[workerID]
+	if w == nil {
+		w = &gvlWorker{}
+		g.workers[workerID] = w
+	}
+
+	// A worker with no native extension reports a flat zero forever. That is
+	// "unknown", not "no contention", and treating it as the latter would let
+	// the controller add threads to a GVL-bound process. Only a counter that has
+	// actually moved counts as a measurement.
+	if !w.haveBaseline {
+		w.lastCumulative, w.lastSeen, w.haveBaseline = cumulative, now, true
+		return
+	}
+
+	dt := now.Sub(w.lastSeen).Seconds()
+	// Sample at most a few times a second: a shorter interval is dominated by
+	// scheduling noise, and every response would otherwise recompute this.
+	if dt < 0.25 {
+		return
+	}
+
+	// A counter that went backwards means the worker was replaced and its
+	// process-local counter restarted. Rebaseline rather than reporting a wild
+	// negative.
+	if cumulative < w.lastCumulative {
+		w.lastCumulative, w.lastSeen = cumulative, now
+		return
+	}
+
+	delta := float64(cumulative - w.lastCumulative)
+	available := float64(threads) * dt * 1e9
+	w.lastCumulative, w.lastSeen = cumulative, now
+
+	if available <= 0 {
+		return
+	}
+	f := delta / available
+	if f > 1 {
+		f = 1
+	}
+	w.fraction = f
+
+	g.recompute()
+}
+
+// recompute aggregates across workers. Caller holds the lock.
+//
+// The MAXIMUM rather than the mean: the question is "is there a process where
+// adding a thread would hurt", and one saturated worker among several is exactly
+// that situation. A mean would dilute it away.
+func (g *GVLTracker) recompute() {
+	var max float64
+	var any bool
+	for _, w := range g.workers {
+		if !w.haveBaseline {
+			continue
+		}
+		any = true
+		if w.fraction > max {
+			max = w.fraction
+		}
+	}
+	g.fraction, g.known = max, any && max > 0
+}
+
+// Fraction reports the current GVL fraction and whether it is a real
+// measurement rather than an absent extension.
+func (g *GVLTracker) Fraction() (float64, bool) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	return g.fraction, g.known
+}
+
+// Forget drops a worker that has gone away.
+func (g *GVLTracker) Forget(workerID int) {
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	delete(g.workers, workerID)
+	g.recompute()
+}

data/go/internal/metrics/gvl_test.go

@@ -0,0 +1,122 @@
+package metrics
+
+import (
+	"testing"
+	"time"
+)
+
+var t0 = time.Unix(1700000000, 0)
+
+// TestGVLTrackerComputesRateOverThreadTime pins the denominator. Six threads can
+// accumulate six seconds of GVL wait per wall second, so the available
+// thread-time is threads*dt -- not dt.
+func TestGVLTrackerComputesRateOverThreadTime(t *testing.T) {
+	g := NewGVLTracker()
+
+	// First observation is only a baseline; a counter alone says nothing.
+	g.Observe(1, 0, 6, t0)
+	if _, known := g.Fraction(); known {
+		t.Error("a single observation should not yield a measurement")
+	}
+
+	// One second later, 6 threads have accumulated 3 seconds of wait between
+	// them: half of the 6 thread-seconds available.
+	g.Observe(1, 3_000_000_000, 6, t0.Add(time.Second))
+	f, known := g.Fraction()
+	if !known {
+		t.Fatal("expected a measurement after two observations")
+	}
+	if f < 0.49 || f > 0.51 {
+		t.Errorf("fraction = %.3f, want ~0.50 (3s of wait over 6 thread-seconds)", f)
+	}
+}
+
+// TestGVLTrackerZeroCounterIsUnknownNotZero is the distinction that keeps the
+// controller safe. A worker without the native extension reports a flat zero
+// forever; reading that as "no contention" would let the controller add threads
+// to a GVL-bound process, which is the exact mistake the measurement prevents.
+func TestGVLTrackerZeroCounterIsUnknownNotZero(t *testing.T) {
+	g := NewGVLTracker()
+	now := t0
+	for i := 0; i < 10; i++ {
+		g.Observe(1, 0, 4, now)
+		now = now.Add(time.Second)
+	}
+	f, known := g.Fraction()
+	if known {
+		t.Errorf("a counter that never moved reported known=%v fraction=%.3f; "+
+			"an absent extension must read as unknown, not as zero contention", known, f)
+	}
+}
+
+// TestGVLTrackerTakesTheWorstWorker: the question is whether ANY process would
+// be hurt by another thread. Averaging would dilute a saturated worker away.
+func TestGVLTrackerTakesTheWorstWorker(t *testing.T) {
+	g := NewGVLTracker()
+
+	g.Observe(1, 0, 4, t0)
+	g.Observe(2, 0, 4, t0)
+	// Worker 1 idle, worker 2 fully GVL-bound.
+	g.Observe(1, 0, 4, t0.Add(time.Second))
+	g.Observe(2, 4_000_000_000, 4, t0.Add(time.Second))
+
+	f, known := g.Fraction()
+	if !known {
+		t.Fatal("expected a measurement")
+	}
+	if f < 0.95 {
+		t.Errorf("fraction = %.3f; the saturated worker should dominate, not be averaged away", f)
+	}
+}
+
+// TestGVLTrackerRebaselinesOnRestart: a replaced worker restarts its
+// process-local counter, which must not read as a huge negative delta.
+func TestGVLTrackerRebaselinesOnRestart(t *testing.T) {
+	g := NewGVLTracker()
+	g.Observe(1, 5_000_000_000, 4, t0)
+	g.Observe(1, 6_000_000_000, 4, t0.Add(time.Second))
+
+	// Worker replaced; counter starts over.
+	g.Observe(1, 100, 4, t0.Add(2*time.Second))
+	g.Observe(1, 400_000_000, 4, t0.Add(3*time.Second))
+
+	f, _ := g.Fraction()
+	if f < 0 || f > 1 {
+		t.Errorf("fraction = %.3f after a counter restart; must stay in [0,1]", f)
+	}
+}
+
+// TestGVLTrackerClampsAtOne guards against a bogus counter producing a fraction
+// above 1, which would read as more-than-total contention.
+func TestGVLTrackerClampsAtOne(t *testing.T) {
+	g := NewGVLTracker()
+	g.Observe(1, 0, 2, t0)
+	g.Observe(1, 999_000_000_000, 2, t0.Add(time.Second))
+	if f, _ := g.Fraction(); f > 1.0 {
+		t.Errorf("fraction = %.3f, want clamped to 1.0", f)
+	}
+}
+
+func TestGVLTrackerIgnoresTinyIntervals(t *testing.T) {
+	g := NewGVLTracker()
+	g.Observe(1, 0, 4, t0)
+	// 1ms apart: dominated by scheduling noise, so it should be skipped rather
+	// than producing a wild rate.
+	g.Observe(1, 1_000_000, 4, t0.Add(time.Millisecond))
+	if _, known := g.Fraction(); known {
+		t.Error("a sub-quarter-second interval should not produce a measurement")
+	}
+}
+
+func TestGVLTrackerForget(t *testing.T) {
+	g := NewGVLTracker()
+	g.Observe(1, 0, 4, t0)
+	g.Observe(1, 4_000_000_000, 4, t0.Add(time.Second))
+	if _, known := g.Fraction(); !known {
+		t.Fatal("expected a measurement")
+	}
+	g.Forget(1)
+	if _, known := g.Fraction(); known {
+		t.Error("forgetting the only worker should leave no measurement")
+	}
+}

data/go/internal/metrics/hist.go

@@ -0,0 +1,204 @@
+// Package metrics aggregates queue time, service time and response latency, and
+// renders them for the control loop and for operators.
+package metrics
+
+import (
+	"math"
+	"math/bits"
+	"sync/atomic"
+)
+
+// A log-linear (HDR-style) histogram: buckets are powers of two subdivided into
+// subCount linear sub-buckets, so relative error is bounded everywhere rather
+// than absolute error being bounded somewhere.
+//
+// Chosen over t-digest deliberately. t-digest buys precision far below the noise
+// floor of any scaling decision, and costs allocation, merge complexity and
+// either locking or per-goroutine state. This is a fixed array of atomics:
+// Record is one bits.Len64 plus one atomic add, lock-free and allocation-free,
+// and the bucket bounds export directly as Prometheus `le` boundaries with no
+// conversion loss.
+const (
+	subBits  = 2
+	subCount = 1 << subBits
+
+	// bucketCount covers the whole uint64 range, so there is no clamping edge
+	// case at either end. At 8 bytes per bucket the entire histogram is 2 KiB.
+	bucketCount = (64-subBits)*subCount + subCount
+)
+
+// Histogram counts values (nanoseconds, in this codebase) into log-linear buckets.
+// The zero value is ready to use. Safe for concurrent Record.
+//
+// Measured cost of Record on this machine (12-core arm64): 2.5ns uncontended,
+// ~138ns with all cores recording in a tight loop. The contended figure is
+// cache-line ping-pong on the shared count and sum counters and is inherent to
+// any shared counter; it is also a worst case that no real workload reaches,
+// since real requests spend microseconds to milliseconds between observations.
+// If the Phase 5 /hello overhead number ever implicates this, the fix is
+// striping the histogram per-P and merging on read -- not a different histogram.
+//
+// Note there is deliberately no running max: it would need a CAS loop that spins
+// whenever the max is climbing (measured at ~64ns/op extra under contention),
+// and the maximum is recoverable from the buckets at read time to the same
+// precision as every other value reported here.
+type Histogram struct {
+	buckets [bucketCount]atomic.Uint64
+	count   atomic.Uint64
+	sum     atomic.Uint64
+}
+
+// bucketIndex maps a value to its bucket.
+//
+// Below subCount*2 the mapping is the identity, so small values get exact
+// buckets; above it, the index is (octave, sub-bucket) packed together. The two
+// regions meet exactly at v == subCount*2, which is what keeps the bucket bounds
+// contiguous.
+func bucketIndex(v uint64) int {
+	if v < subCount*2 {
+		return int(v)
+	}
+	msb := bits.Len64(v) - 1
+	shift := msb - subBits
+	sub := (v >> uint(shift)) & (subCount - 1)
+	return (shift+1)*subCount + int(sub)
+}
+
+// bucketBounds returns the half-open [lo, hi) range a bucket covers.
+func bucketBounds(i int) (uint64, uint64) {
+	if i < subCount*2 {
+		return uint64(i), uint64(i) + 1
+	}
+	shift := uint(i/subCount - 1)
+	sub := uint64(i % subCount)
+	lo := (subCount + sub) << shift
+	hi := (subCount + sub + 1) << shift
+	// The topmost bucket's true upper edge is 2^64, which wraps to 0. Report the
+	// largest representable value so bounds stay monotonic and the Prometheus
+	// `le` export never emits a nonsensical 0 as the final boundary.
+	if hi <= lo {
+		hi = math.MaxUint64
+	}
+	return lo, hi
+}
+
+// Record adds one observation. Three atomic adds, no allocation, no branching
+// beyond the bucket-index computation.
+func (h *Histogram) Record(v uint64) {
+	h.buckets[bucketIndex(v)].Add(1)
+	h.count.Add(1)
+	h.sum.Add(v)
+}
+
+// Count is the number of observations recorded.
+func (h *Histogram) Count() uint64 { return h.count.Load() }
+
+// Sum is the total of all observations.
+func (h *Histogram) Sum() uint64 { return h.sum.Load() }
+
+// Max is the largest observation recorded, as the midpoint of the highest
+// non-empty bucket. Like every other value this type reports, it carries the
+// histogram's 12.5% relative error rather than being exact -- which is the
+// honest thing for a bucketed histogram to say about its tail.
+func (h *Histogram) Max() uint64 {
+	for i := bucketCount - 1; i >= 0; i-- {
+		if h.buckets[i].Load() != 0 {
+			lo, hi := bucketBounds(i)
+			return lo + (hi-lo)/2
+		}
+	}
+	return 0
+}
+
+// Mean is the arithmetic mean, or 0 with no observations.
+func (h *Histogram) Mean() float64 {
+	n := h.count.Load()
+	if n == 0 {
+		return 0
+	}
+	return float64(h.sum.Load()) / float64(n)
+}
+
+// Reset zeroes the histogram for reuse. Not atomic with respect to concurrent
+// Record; used only on a ring slot that has just rotated out of the write path.
+func (h *Histogram) Reset() {
+	for i := range h.buckets {
+		h.buckets[i].Store(0)
+	}
+	h.count.Store(0)
+	h.sum.Store(0)
+}
+
+// AddTo merges this histogram's counts into dst.
+func (h *Histogram) AddTo(dst *Histogram) {
+	for i := range h.buckets {
+		if n := h.buckets[i].Load(); n != 0 {
+			dst.buckets[i].Add(n)
+		}
+	}
+	dst.count.Add(h.count.Load())
+	dst.sum.Add(h.sum.Load())
+}
+
+// Quantile returns the value at quantile q (0..1).
+//
+// The bucket midpoint is returned rather than an edge, which bounds the relative
+// error at 1/(2*subCount) = 12.5%. That is far tighter than the run-to-run
+// variance of any load test, and far coarser than anything the control loop
+// could act on differently.
+func (h *Histogram) Quantile(q float64) uint64 {
+	total := h.count.Load()
+	if total == 0 {
+		return 0
+	}
+	if q <= 0 {
+		q = 0
+	} else if q > 1 {
+		q = 1
+	}
+
+	// Rank is 1-based: the smallest observation is rank 1.
+	target := uint64(q * float64(total))
+	if target == 0 {
+		target = 1
+	}
+
+	var cum uint64
+	for i := range h.buckets {
+		cum += h.buckets[i].Load()
+		if cum >= target {
+			lo, hi := bucketBounds(i)
+			return lo + (hi-lo)/2
+		}
+	}
+	return h.Max()
+}
+
+// Bucket is one exported histogram bucket.
+type Bucket struct {
+	// UpperBound is the exclusive upper edge, suitable as a Prometheus `le`.
+	UpperBound uint64
+	// CumulativeCount is the number of observations <= UpperBound, matching
+	// Prometheus histogram semantics.
+	CumulativeCount uint64
+}
+
+// Buckets returns the non-empty portion of the histogram in cumulative form.
+// Trailing empty buckets are omitted; the caller appends the +Inf bucket.
+func (h *Histogram) Buckets() []Bucket {
+	out := make([]Bucket, 0, 64)
+	var cum uint64
+	total := h.count.Load()
+	for i := range h.buckets {
+		cum += h.buckets[i].Load()
+		if cum == 0 {
+			continue
+		}
+		_, hi := bucketBounds(i)
+		out = append(out, Bucket{UpperBound: hi, CumulativeCount: cum})
+		if cum == total {
+			break
+		}
+	}
+	return out
+}