fix(metrics): bind() at cardinality limit binds directly to overflow

The previous Fallback path re-routed every bound.add() through the
unbound measure() path, creating a ~25x perf cliff at the cardinality
limit (~50ns vs ~1.8ns) and letting attribution drift across delta
eviction cycles as space freed and refilled.

ValueMap::bind() now looks up or lazily creates the overflow
TrackerEntry at the limit and returns a direct handle to it. The bound
handle writes directly to overflow via a single atomic update for its
lifetime — perf parity with a normal bind. To recover after delta
eviction frees space, drop the handle and rebind.

Spec-aligned with open-telemetry/opentelemetry-specification#5050:
overflow data lands in the otel.metric.overflow=true bucket (MUST)
and per-call attribute lookup is bypassed (SHOULD).

Bench (Apple M4 Max):
  Counter_Bound_AtOverflow_Delta:    1.82 ns
  Histogram_Bound_AtOverflow_Delta:  6.58 ns

Author: bryantbiggs

opentelemetry-sdk/CHANGELOG.md

@@ -14,10 +14,13 @@
   attribute set always aggregate into the same data point, including the empty
   attribute set. Bound entries are never evicted during delta collection while
   a handle exists — idle cycles produce no export but the tracker persists. If
-  `bind()` is called at the cardinality limit, the handle transparently falls
-  back to the unbound measurement path. Gated behind the
-  `experimental_metrics_bound_instruments` feature flag. Benchmarks show ~28x
-  speedup for counter operations and ~9x for histograms.
+  `bind()` is called at the cardinality limit, the handle binds directly to
+  the overflow tracker — its writes stay on the same direct (no-lookup) hot
+  path and consistently land in the `otel.metric.overflow=true` bucket for
+  the lifetime of the handle. To recover a bound handle after delta collection
+  frees space, drop the existing handle and call `bind()` again. Gated behind
+  the `experimental_metrics_bound_instruments` feature flag. Benchmarks show
+  ~28x speedup for counter operations and ~9x for histograms.
 - Delta metrics collection now uses in-place eviction instead of draining the
   HashMap on every collect cycle. Stale attribute sets that received no measurements
   since the last collection are evicted. Note: recovery from cardinality overflow

opentelemetry-sdk/benches/bound_instruments.rs

@@ -1,21 +1,24 @@
 use criterion::{criterion_group, criterion_main, Criterion};
 use opentelemetry::{metrics::MeterProvider as _, Key, KeyValue};
-use opentelemetry_sdk::metrics::{ManualReader, SdkMeterProvider, Stream, Temporality};
+use opentelemetry_sdk::metrics::{Instrument, ManualReader, SdkMeterProvider, Stream, Temporality};
 
 // Run this benchmark with:
 // cargo bench --bench bound_instruments --features metrics,experimental_metrics_custom_reader,experimental_metrics_bound_instruments,spec_unstable_metrics_views
 //
 // Apple M4 Max, 16 cores (12 performance + 4 efficiency), macOS 15.4
 //
 // Results (3 attributes: method, status, path):
-// Counter_Unbound_Delta             time:   [53.20 ns]
-// Counter_Bound_Delta               time:   [1.87 ns]    ~28x faster
-// Counter_Bound_With_View_Delta     time:   [~1.9 ns]    view filter applied at bind, not on hot path
-// Histogram_Unbound_Delta           time:   [58.58 ns]
-// Histogram_Bound_Delta             time:   [6.57 ns]    ~8.9x faster
-// Counter_Bound_Multithread/2       time:   [22.19 µs]   (100 adds/thread)
-// Counter_Bound_Multithread/4       time:   [35.32 µs]   (100 adds/thread)
-// Counter_Bound_Multithread/8       time:   [66.49 µs]   (100 adds/thread)
+// Counter_Unbound_Delta              time:   [50.20 ns]
+// Counter_Bound_Delta                time:   [ 1.80 ns]  ~28x faster
+// Counter_Bound_With_View_Delta      time:   [ 1.82 ns]  view filter applied at bind, not on hot path
+// Counter_Bound_AtOverflow_Delta     time:   [ 1.82 ns]  bind() at cardinality limit binds directly to the overflow
+//                                                        tracker — perf parity with a normal bind, no per-call resolution
+// Histogram_Unbound_Delta            time:   [58.64 ns]
+// Histogram_Bound_Delta              time:   [ 6.50 ns]  ~9.0x faster
+// Histogram_Bound_AtOverflow_Delta   time:   [ 6.58 ns]  perf parity with a normal bind
+// Counter_Bound_Multithread/2        time:   [21.59 µs]  (100 adds/thread)
+// Counter_Bound_Multithread/4        time:   [37.21 µs]  (100 adds/thread)
+// Counter_Bound_Multithread/8        time:   [71.70 µs]  (100 adds/thread)
 //
 // Note: criterion does not fail CI on regression by itself. These numbers are
 // reference values for human review; use `cargo criterion --baseline` locally
@@ -90,6 +93,40 @@ fn bench_bound_instruments(c: &mut Criterion) {
         });
     }
 
+    // Counter: Bound at overflow — confirms that binding when the cardinality
+    // limit is exhausted yields the same hot-path performance as a normal bind
+    // (writes go directly to the overflow tracker, no per-call resolution).
+    {
+        let cardinality_limit = 4;
+        let view = move |i: &Instrument| {
+            if i.name() == "bound_at_overflow" {
+                Stream::builder()
+                    .with_cardinality_limit(cardinality_limit)
+                    .build()
+                    .ok()
+            } else {
+                None
+            }
+        };
+        let reader = ManualReader::builder()
+            .with_temporality(Temporality::Delta)
+            .build();
+        let provider = SdkMeterProvider::builder()
+            .with_reader(reader)
+            .with_view(view)
+            .build();
+        let meter = provider.meter("bench");
+        let counter = meter.u64_counter("bound_at_overflow").build();
+        // Saturate cardinality with unbound calls so bind() lands in overflow.
+        for i in 0..cardinality_limit {
+            counter.add(1, &[KeyValue::new("filler", i as i64)]);
+        }
+        let bound = counter.bind(&attrs);
+        group.bench_function("Counter_Bound_AtOverflow_Delta", |b| {
+            b.iter(|| bound.add(1));
+        });
+    }
+
     // Histogram: Unbound vs Bound (Delta)
     {
         let provider = create_provider(Temporality::Delta);
@@ -110,6 +147,37 @@ fn bench_bound_instruments(c: &mut Criterion) {
         });
     }
 
+    // Histogram: Bound at overflow — same property as the counter version.
+    {
+        let cardinality_limit = 4;
+        let view = move |i: &Instrument| {
+            if i.name() == "bound_hist_at_overflow" {
+                Stream::builder()
+                    .with_cardinality_limit(cardinality_limit)
+                    .build()
+                    .ok()
+            } else {
+                None
+            }
+        };
+        let reader = ManualReader::builder()
+            .with_temporality(Temporality::Delta)
+            .build();
+        let provider = SdkMeterProvider::builder()
+            .with_reader(reader)
+            .with_view(view)
+            .build();
+        let meter = provider.meter("bench");
+        let histogram = meter.f64_histogram("bound_hist_at_overflow").build();
+        for i in 0..cardinality_limit {
+            histogram.record(1.5, &[KeyValue::new("filler", i as i64)]);
+        }
+        let bound = histogram.bind(&attrs);
+        group.bench_function("Histogram_Bound_AtOverflow_Delta", |b| {
+            b.iter(|| bound.record(1.5));
+        });
+    }
+
     // Multi-threaded bound counter
     for num_threads in [2, 4, 8] {
         let provider = create_provider(Temporality::Delta);

opentelemetry-sdk/src/metrics/internal/histogram.rs

@@ -14,7 +14,7 @@ use opentelemetry::KeyValue;
 use super::aggregate::{AggregateTimeInitiator, AttributeSetFilter};
 use super::{Aggregator, ComputeAggregation, Measure, Number, ValueMap};
 #[cfg(feature = "experimental_metrics_bound_instruments")]
-use super::{BoundMeasure, TrackerEntry};
+use super::{BoundFallbackHandle, BoundMeasure, TrackerEntry};
 
 impl<T> Aggregator for Mutex<Buckets<T>>
 where
@@ -72,48 +72,30 @@ impl<T: Number> Buckets<T> {
     }
 }
 
-#[cfg(feature = "experimental_metrics_bound_instruments")]
-enum BoundHistogramInner<T: Number> {
-    /// Fast path: dedicated tracker for this attribute set.
-    Direct {
-        tracker: Arc<TrackerEntry<Mutex<Buckets<T>>>>,
-        bounds: Vec<f64>,
-    },
-    /// Overflow fallback: delegates to the unbound Measure::call() path.
-    Fallback {
-        measure: Arc<dyn Measure<T>>,
-        attrs: Vec<KeyValue>,
-    },
-}
-
+/// Pre-bound histogram handle: writes go directly to a fixed `TrackerEntry`
+/// without per-call attribute lookup. The `tracker` is either a dedicated entry
+/// for the bound attribute set, or — if bind() hit the cardinality limit — the
+/// shared overflow tracker.
 #[cfg(feature = "experimental_metrics_bound_instruments")]
 struct BoundHistogramHandle<T: Number> {
-    inner: BoundHistogramInner<T>,
+    tracker: Arc<TrackerEntry<Mutex<Buckets<T>>>>,
+    bounds: Vec<f64>,
 }
 
 #[cfg(feature = "experimental_metrics_bound_instruments")]
 impl<T: Number> BoundMeasure<T> for BoundHistogramHandle<T> {
     fn call(&self, measurement: T) {
-        match &self.inner {
-            BoundHistogramInner::Direct { tracker, bounds } => {
-                let f = measurement.into_float();
-                let index = bounds.partition_point(|&x| x < f);
-                tracker.aggregator.update((measurement, index));
-                tracker.has_been_updated.store(true, Ordering::Release);
-            }
-            BoundHistogramInner::Fallback { measure, attrs } => {
-                measure.call(measurement, attrs);
-            }
-        }
+        let f = measurement.into_float();
+        let index = self.bounds.partition_point(|&x| x < f);
+        self.tracker.aggregator.update((measurement, index));
+        self.tracker.has_been_updated.store(true, Ordering::Release);
     }
 }
 
 #[cfg(feature = "experimental_metrics_bound_instruments")]
 impl<T: Number> Drop for BoundHistogramHandle<T> {
     fn drop(&mut self) {
-        if let BoundHistogramInner::Direct { tracker, .. } = &self.inner {
-            tracker.bound_count.fetch_sub(1, Ordering::Relaxed);
-        }
+        self.tracker.bound_count.fetch_sub(1, Ordering::Relaxed);
     }
 }
 
@@ -291,17 +273,16 @@ where
         self.filter.apply(attrs, |filtered| {
             bound_attrs = filtered.to_vec();
         });
-        let inner = match self.value_map.bind(&bound_attrs) {
-            Some(tracker) => BoundHistogramInner::Direct {
+        match self.value_map.bind(&bound_attrs) {
+            Some(tracker) => Box::new(BoundHistogramHandle {
                 tracker,
                 bounds: self.bounds.clone(),
-            },
-            None => BoundHistogramInner::Fallback {
-                measure: fallback,
-                attrs: bound_attrs,
-            },
-        };
-        Box::new(BoundHistogramHandle { inner })
+            }),
+            // Trackers RwLock is poisoned — extremely rare. Hand back a fallback
+            // handle whose writes will silently drop (mirroring `measure()`'s
+            // own poison handling) rather than panic on the user's hot path.
+            None => Box::new(BoundFallbackHandle::new(fallback, bound_attrs)),
+        }
     }
 }
 

opentelemetry-sdk/src/metrics/internal/mod.rs

@@ -198,10 +198,16 @@ where
     /// The caller can then call `tracker.aggregator.update()` directly, bypassing the
     /// full lookup path on subsequent measurements.
     ///
-    /// Returns `None` if the cardinality limit has been reached. The caller should
-    /// fall back to the unbound `Measure::call()` path, which handles overflow
-    /// correctly and enables automatic recovery when space opens up after delta
-    /// collection evicts stale entries.
+    /// When the cardinality limit has been reached, the returned tracker is the
+    /// overflow tracker (the same one unbound `measure()` calls write to at
+    /// overflow), preserving the bind() perf contract — every subsequent
+    /// `bound.add()` call is a direct write, regardless of cardinality state.
+    /// The handle remains permanently bound to overflow for its lifetime;
+    /// to recover after space frees up, drop and re-bind.
+    ///
+    /// Returns `None` only if the trackers RwLock is poisoned, in which case
+    /// the caller should produce a noop bound handle so measurements are
+    /// silently dropped rather than panicking on the user's hot path.
     #[cfg(feature = "experimental_metrics_bound_instruments")]
     fn bind(&self, attributes: &[KeyValue]) -> Option<Arc<TrackerEntry<A>>> {
         if attributes.is_empty() {
@@ -231,7 +237,7 @@ where
 
         // Slow path: write lock, insert if missing.
         let Ok(mut trackers) = self.trackers.write() else {
-            // Lock poisoned — return None so caller falls back to unbound path
+            // Lock poisoned — caller will produce a noop bound handle.
             return None;
         };
 
@@ -254,25 +260,27 @@ where
             self.count.fetch_add(1, Ordering::SeqCst);
             Some(new_tracker)
         } else {
-            // Over cardinality limit — return None so the caller falls back to the
-            // unbound Measure::call() path. This ensures:
-            // 1. Overflow data is attributed correctly (same as unbound at overflow)
-            // 2. Automatic recovery when delta collect evicts stale entries
-            // 3. bound_count is not inflated on the overflow tracker
+            // Over cardinality limit — bind directly to the overflow tracker so
+            // the bound handle keeps its perf contract (no per-call lookup) and
+            // its writes land predictably in the overflow bucket. This matches
+            // the spec SHOULD that the SDK pre-resolve aggregator state at bind
+            // time, and the spec MUST that bound recordings behave identically
+            // to unbound recordings (which themselves route to overflow once
+            // cardinality is exhausted). See open-telemetry/opentelemetry-specification#5050.
             //
-            // TODO: If bind() is called during overflow, the handle remains in fallback
-            // mode permanently even after delta collect frees space. Not an issue in
-            // practice since bind() typically occurs at application startup before
-            // cardinality fills up. Future options to revisit:
-            // - Internally adjust bindings from overflow to normal during delta collect
-            // - Exclude bind() from cardinality capping (users leveraging bind() know
-            //   their bound instruments always report properly and never overflow)
-            // See: https://github.com/open-telemetry/opentelemetry-rust/pull/3392#discussion_r2860376315
+            // The overflow tracker is created lazily here if it doesn't exist
+            // yet — mirrors the lazy creation in `measure()` (line above where
+            // overflow is inserted on first overflowing measurement).
+            let overflow_tracker = trackers
+                .entry(stream_overflow_attributes().clone())
+                .or_insert_with(|| Arc::new(TrackerEntry::<A>::new(&self.config)))
+                .clone();
+            overflow_tracker.bound_count.fetch_add(1, Ordering::Relaxed);
             otel_debug!(
                 name: "BoundInstrument.CardinalityOverflow",
-                message = "bind() called at cardinality limit, falling back to unbound path"
+                message = "bind() called at cardinality limit, attributing to overflow bucket"
             );
-            None
+            Some(overflow_tracker)
         }
     }
 

opentelemetry-sdk/src/metrics/internal/sum.rs

@@ -10,7 +10,7 @@ use super::aggregate::{AggregateTimeInitiator, AttributeSetFilter};
 use super::{Aggregator, AtomicTracker, ComputeAggregation, Measure, Number};
 use super::{AtomicallyUpdate, ValueMap};
 #[cfg(feature = "experimental_metrics_bound_instruments")]
-use super::{BoundMeasure, TrackerEntry};
+use super::{BoundFallbackHandle, BoundMeasure, TrackerEntry};
 
 struct Increment<T>
 where
@@ -43,48 +43,28 @@ where
     }
 }
 
-#[cfg(feature = "experimental_metrics_bound_instruments")]
-enum BoundSumInner<T: Number> {
-    /// Fast path: dedicated tracker for this attribute set.
-    Direct {
-        tracker: Arc<TrackerEntry<Increment<T>>>,
-    },
-    /// Overflow fallback: delegates to the unbound Measure::call() path.
-    /// This happens when bind() is called at/over the cardinality limit.
-    /// Using the unbound path ensures correct overflow attribution and
-    /// automatic recovery when delta collect opens up space.
-    Fallback {
-        measure: Arc<dyn Measure<T>>,
-        attrs: Vec<KeyValue>,
-    },
-}
-
+/// Pre-bound counter handle: writes go directly to a fixed `TrackerEntry` without
+/// per-call attribute lookup. The `tracker` is either a dedicated entry for the
+/// bound attribute set, or — if bind() hit the cardinality limit — the shared
+/// overflow tracker. Either way, `call()` is a single atomic increment and a
+/// release store; no map lookup, no lock acquisition.
 #[cfg(feature = "experimental_metrics_bound_instruments")]
 struct BoundSumHandle<T: Number> {
-    inner: BoundSumInner<T>,
+    tracker: Arc<TrackerEntry<Increment<T>>>,
 }
 
 #[cfg(feature = "experimental_metrics_bound_instruments")]
 impl<T: Number> BoundMeasure<T> for BoundSumHandle<T> {
     fn call(&self, measurement: T) {
-        match &self.inner {
-            BoundSumInner::Direct { tracker } => {
-                tracker.aggregator.update(measurement);
-                tracker.has_been_updated.store(true, Ordering::Release);
-            }
-            BoundSumInner::Fallback { measure, attrs } => {
-                measure.call(measurement, attrs);
-            }
-        }
+        self.tracker.aggregator.update(measurement);
+        self.tracker.has_been_updated.store(true, Ordering::Release);
     }
 }
 
 #[cfg(feature = "experimental_metrics_bound_instruments")]
 impl<T: Number> Drop for BoundSumHandle<T> {
     fn drop(&mut self) {
-        if let BoundSumInner::Direct { tracker } = &self.inner {
-            tracker.bound_count.fetch_sub(1, Ordering::Relaxed);
-        }
+        self.tracker.bound_count.fetch_sub(1, Ordering::Relaxed);
     }
 }
 
@@ -211,14 +191,13 @@ where
         self.filter.apply(attrs, |filtered| {
             bound_attrs = filtered.to_vec();
         });
-        let inner = match self.value_map.bind(&bound_attrs) {
-            Some(tracker) => BoundSumInner::Direct { tracker },
-            None => BoundSumInner::Fallback {
-                measure: fallback,
-                attrs: bound_attrs,
-            },
-        };
-        Box::new(BoundSumHandle { inner })
+        match self.value_map.bind(&bound_attrs) {
+            Some(tracker) => Box::new(BoundSumHandle { tracker }),
+            // Trackers RwLock is poisoned — extremely rare. Hand back a fallback
+            // handle whose writes will silently drop (mirroring `measure()`'s
+            // own poison handling) rather than panic on the user's hot path.
+            None => Box::new(BoundFallbackHandle::new(fallback, bound_attrs)),
+        }
     }
 }