prometheus: introduce an experimental sharded counter

Author: cagedmantis

go.mod

@@ -3,6 +3,7 @@ module github.com/prometheus/client_golang
 go 1.25.0
 
 require (
+	argc.dev/goexp v0.0.0-20260710001111-8c1f88208172
 	github.com/beorn7/perks v1.0.1
 	github.com/cespare/xxhash/v2 v2.3.0
 	github.com/google/go-cmp v0.7.0

go.sum

@@ -1,3 +1,5 @@
+argc.dev/goexp v0.0.0-20260710001111-8c1f88208172 h1:PET7L5h+6EjqOnYjG2Z5sxuMHx2NFmn4OjA/ls/ywEI=
+argc.dev/goexp v0.0.0-20260710001111-8c1f88208172/go.mod h1:5KW5TTv68+fSFL3H+qywujHM1tkwM9JWcc2+ZtT2Vrc=
 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.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=

prometheus/counter.go

@@ -15,10 +15,10 @@ package prometheus
 
 import (
 	"errors"
-	"math"
 	"sync/atomic"
 	"time"
 
+	xsync "argc.dev/goexp/sync"
 	dto "github.com/prometheus/client_model/go"
 	"google.golang.org/protobuf/types/known/timestamppb"
 )
@@ -95,19 +95,29 @@ func NewCounter(opts CounterOpts) Counter {
 	if opts.now == nil {
 		opts.now = time.Now
 	}
-	result := &counter{desc: desc, labelPairs: desc.constLabelPairs, now: opts.now}
+	result := &counter{
+		desc:       desc,
+		labelPairs: desc.constLabelPairs,
+		valBits:    xsync.NewCounter[float64](),
+		valInt:     xsync.NewCounter[int64](),
+		now:        opts.now,
+	}
 	result.init(result) // Init self-collection.
 	result.createdTs = timestamppb.New(opts.now())
 	return result
 }
 
 type counter struct {
-	// valBits contains the bits of the represented float64 value, while
-	// valInt stores values that are exact integers. Both have to go first
-	// in the struct to guarantee alignment for atomic operations.
-	// http://golang.org/pkg/sync/atomic/#pkg-note-BUG
-	valBits uint64
-	valInt  uint64
+	// valInt accumulates the exact integer part of the counter (Inc calls
+	// and Add calls with integral values), while valBits accumulates values
+	// that cannot be represented as an int64. Both are per-P sharded
+	// counters (see argc.dev/goexp/sync): increments happen on hot paths and
+	// are made cheap and contention-free by striping them across processors,
+	// whereas reads (only at collection time) sum the shards. The split
+	// between integer and floating-point tracking is kept for precision, and
+	// the two are added up in the get method.
+	valBits *xsync.Counter[float64]
+	valInt  *xsync.Counter[int64]
 
 	selfCollector
 	desc *Desc
@@ -129,19 +139,13 @@ func (c *counter) Add(v float64) {
 		panic(errors.New("counter cannot decrease in value"))
 	}
 
-	ival := uint64(v)
+	ival := int64(v)
 	if float64(ival) == v {
-		atomic.AddUint64(&c.valInt, ival)
+		c.valInt.Add(ival)
 		return
 	}
 
-	for {
-		oldBits := atomic.LoadUint64(&c.valBits)
-		newBits := math.Float64bits(math.Float64frombits(oldBits) + v)
-		if atomic.CompareAndSwapUint64(&c.valBits, oldBits, newBits) {
-			return
-		}
-	}
+	c.valBits.Add(v)
 }
 
 func (c *counter) AddWithExemplar(v float64, e Labels) {
@@ -150,13 +154,11 @@ func (c *counter) AddWithExemplar(v float64, e Labels) {
 }
 
 func (c *counter) Inc() {
-	atomic.AddUint64(&c.valInt, 1)
+	c.valInt.Add(1)
 }
 
 func (c *counter) get() float64 {
-	fval := math.Float64frombits(atomic.LoadUint64(&c.valBits))
-	ival := atomic.LoadUint64(&c.valInt)
-	return fval + float64(ival)
+	return c.valBits.Value() + float64(c.valInt.Value())
 }
 
 func (c *counter) Write(out *dto.Metric) error {
@@ -216,7 +218,13 @@ func (v2) NewCounterVec(opts CounterVecOpts) *CounterVec {
 			if len(lvs) != len(desc.variableLabels.names) {
 				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels.names, lvs))
 			}
-			result := &counter{desc: desc, labelPairs: MakeLabelPairs(desc, lvs), now: opts.now}
+			result := &counter{
+				desc:       desc,
+				labelPairs: MakeLabelPairs(desc, lvs),
+				valBits:    xsync.NewCounter[float64](),
+				valInt:     xsync.NewCounter[int64](),
+				now:        opts.now,
+			}
 			result.init(result) // Init self-collection.
 			result.createdTs = timestamppb.New(opts.now())
 			return result

prometheus/counter_test.go

@@ -34,25 +34,25 @@ func TestCounterAdd(t *testing.T) {
 		now:         func() time.Time { return now },
 	}).(*counter)
 	counter.Inc()
-	if expected, got := 0.0, math.Float64frombits(counter.valBits); expected != got {
+	if expected, got := 0.0, counter.valBits.Value(); expected != got {
 		t.Errorf("Expected %f, got %f.", expected, got)
 	}
-	if expected, got := uint64(1), counter.valInt; expected != got {
+	if expected, got := int64(1), counter.valInt.Value(); expected != got {
 		t.Errorf("Expected %d, got %d.", expected, got)
 	}
 	counter.Add(42)
-	if expected, got := 0.0, math.Float64frombits(counter.valBits); expected != got {
+	if expected, got := 0.0, counter.valBits.Value(); expected != got {
 		t.Errorf("Expected %f, got %f.", expected, got)
 	}
-	if expected, got := uint64(43), counter.valInt; expected != got {
+	if expected, got := int64(43), counter.valInt.Value(); expected != got {
 		t.Errorf("Expected %d, got %d.", expected, got)
 	}
 
 	counter.Add(24.42)
-	if expected, got := 24.42, math.Float64frombits(counter.valBits); expected != got {
+	if expected, got := 24.42, counter.valBits.Value(); expected != got {
 		t.Errorf("Expected %f, got %f.", expected, got)
 	}
-	if expected, got := uint64(43), counter.valInt; expected != got {
+	if expected, got := int64(43), counter.valInt.Value(); expected != got {
 		t.Errorf("Expected %d, got %d.", expected, got)
 	}
 
@@ -153,26 +153,26 @@ func TestCounterAddInf(t *testing.T) {
 	}).(*counter)
 
 	counter.Inc()
-	if expected, got := 0.0, math.Float64frombits(counter.valBits); expected != got {
+	if expected, got := 0.0, counter.valBits.Value(); expected != got {
 		t.Errorf("Expected %f, got %f.", expected, got)
 	}
-	if expected, got := uint64(1), counter.valInt; expected != got {
+	if expected, got := int64(1), counter.valInt.Value(); expected != got {
 		t.Errorf("Expected %d, got %d.", expected, got)
 	}
 
 	counter.Add(math.Inf(1))
-	if expected, got := math.Inf(1), math.Float64frombits(counter.valBits); expected != got {
+	if expected, got := math.Inf(1), counter.valBits.Value(); expected != got {
 		t.Errorf("valBits expected %f, got %f.", expected, got)
 	}
-	if expected, got := uint64(1), counter.valInt; expected != got {
+	if expected, got := int64(1), counter.valInt.Value(); expected != got {
 		t.Errorf("valInts expected %d, got %d.", expected, got)
 	}
 
 	counter.Inc()
-	if expected, got := math.Inf(1), math.Float64frombits(counter.valBits); expected != got {
+	if expected, got := math.Inf(1), counter.valBits.Value(); expected != got {
 		t.Errorf("Expected %f, got %f.", expected, got)
 	}
-	if expected, got := uint64(2), counter.valInt; expected != got {
+	if expected, got := int64(2), counter.valInt.Value(); expected != got {
 		t.Errorf("Expected %d, got %d.", expected, got)
 	}
 
@@ -203,10 +203,10 @@ func TestCounterAddLarge(t *testing.T) {
 	// large overflows the underlying type and should therefore be stored in valBits.
 	large := math.Nextafter(float64(math.MaxUint64), 1e20)
 	counter.Add(large)
-	if expected, got := large, math.Float64frombits(counter.valBits); expected != got {
+	if expected, got := large, counter.valBits.Value(); expected != got {
 		t.Errorf("valBits expected %f, got %f.", expected, got)
 	}
-	if expected, got := uint64(0), counter.valInt; expected != got {
+	if expected, got := int64(0), counter.valInt.Value(); expected != got {
 		t.Errorf("valInts expected %d, got %d.", expected, got)
 	}
 
@@ -236,10 +236,10 @@ func TestCounterAddSmall(t *testing.T) {
 
 	small := 0.000000000001
 	counter.Add(small)
-	if expected, got := small, math.Float64frombits(counter.valBits); expected != got {
+	if expected, got := small, counter.valBits.Value(); expected != got {
 		t.Errorf("valBits expected %f, got %f.", expected, got)
 	}
-	if expected, got := uint64(0), counter.valInt; expected != got {
+	if expected, got := int64(0), counter.valInt.Value(); expected != got {
 		t.Errorf("valInts expected %d, got %d.", expected, got)
 	}