perf(sdk): add optional rapidhash for ValueMap HashMaps in metrics hot path

bryantbiggs · bryantbiggs · commit 5e4684bf96af · 2026-02-24T15:01:30.000-06:00
Replace the default SipHash-1-3 hasher with rapidhash (wyhash successor) behind an opt-in `metrics-use-rapidhash` feature flag for the HashMap used in ValueMap::trackers. SipHash's HashDoS resistance is unnecessary here since ValueMap is pub(crate) and keys are not attacker-controlled. rapidhash was selected after benchmarking four hashers (ahash, foldhash, rapidhash, std SipHash) on actual Vec<KeyValue> keys matching the ValueMap workload (1600 time series, 2-8 attributes per entry, mixed read/write). Benchmark results (Apple Silicon, aarch64-apple-darwin): | Benchmark (4 attrs) | ahash | foldhash | rapidhash | std SipHash | |--------------------------|---------|----------|-----------|-------------| | hash_only | 31.5 µs | 30.7 µs | 29.9 µs | 60.0 µs | | lookup_hit | 81.2 µs | 71.0 µs | 70.1 µs | 104.8 µs | | lookup_miss | 2.24 µs | 2.46 µs | 2.13 µs | 4.10 µs | | insert | 207 µs | 198 µs | 196 µs | 235 µs | | mixed_rw (ValueMap path) | 170 µs | 155 µs | 153 µs | 218 µs | Key findings: - rapidhash is 10% faster than ahash on the mixed read/write path that most closely models ValueMap::measure() - foldhash (now hashbrown's default hasher) is 8% faster than ahash - ahash has known unresolved performance regressions on ARM (#194, ~40% regression on M1 from 0.8.6->0.8.7) and AMD (#190, 73-151% regression with target-cpu=native) - ahash has had no throughput-focused optimization work merged in 2024-2025; three VAES PRs (#144, #186, #187) have been stalled for 2+ years - foldhash replaced ahash as the default hasher in hashbrown (PR #563) - rapidhash is the official successor to wyhash, adopted by Chromium and Microsoft Terminal The feature is opt-in to avoid adding a mandatory dependency. When `metrics-use-rapidhash` is not enabled, the standard library HashMap (SipHash) is used. Also adds a hasher_comparison benchmark for reproducing these results. Refs: #3371
diff --git a/opentelemetry-sdk/Cargo.toml b/opentelemetry-sdk/Cargo.toml
@@ -12,6 +12,7 @@ autobenches = false
 
 [dependencies]
 opentelemetry = { workspace = true }
+rapidhash = { version = "4", optional = true }
 opentelemetry-http = { workspace = true, optional = true }
 futures-channel = { workspace = true }
 futures-executor = { workspace = true }
@@ -34,7 +35,10 @@ all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
 [dev-dependencies]
+ahash = "0.8"
 criterion = { workspace = true, features = ["html_reports"] }
+foldhash = "0.2.0"
+rapidhash = "4"
 rstest = { workspace = true }
 temp-env = { workspace = true }
 
@@ -59,6 +63,7 @@ experimental_logs_batch_log_processor_with_async_runtime = ["logs", "experimenta
 experimental_logs_concurrent_log_processor = ["logs"]
 experimental_trace_batch_span_processor_with_async_runtime = ["tokio/sync", "trace", "experimental_async_runtime"]
 experimental_metrics_disable_name_validation = ["metrics"]
+metrics-use-rapidhash = ["metrics", "rapidhash"]
 bench_profiling = []
 
 [[bench]]
@@ -124,6 +129,11 @@ name = "log"
 harness = false
 required-features = ["logs"]
 
+[[bench]]
+name = "hasher_comparison"
+harness = false
+required-features = ["metrics"]
+
 [lib]
 bench = false
 
diff --git a/opentelemetry-sdk/benches/hasher_comparison.rs b/opentelemetry-sdk/benches/hasher_comparison.rs
@@ -0,0 +1,285 @@
+//! Benchmark comparing ahash, foldhash, and rapidhash for ValueMap's HashMap.
+//!
+//! The key type is `Vec<KeyValue>`, which is how metrics attributes are stored.
+//! We test lookup (hit/miss) and insert across different attribute set sizes.
+
+use criterion::{criterion_group, criterion_main, Criterion};
+use opentelemetry::KeyValue;
+use std::collections::HashMap;
+use std::hash::{BuildHasher, Hash};
+use std::time::Duration;
+
+// --- Hasher setup ---
+
+type AHashMap<K, V> = HashMap<K, V, ahash::RandomState>;
+type FoldHashMap<K, V> = HashMap<K, V, foldhash::fast::RandomState>;
+type RapidHashMap<K, V> = HashMap<K, V, rapidhash::fast::RandomState>;
+type StdHashMap<K, V> = HashMap<K, V>;
+
+fn new_ahash_map<K: Hash + Eq, V>(cap: usize) -> AHashMap<K, V> {
+    HashMap::with_capacity_and_hasher(cap, ahash::RandomState::new())
+}
+
+fn new_foldhash_map<K: Hash + Eq, V>(cap: usize) -> FoldHashMap<K, V> {
+    HashMap::with_capacity_and_hasher(cap, foldhash::fast::RandomState::default())
+}
+
+fn new_rapidhash_map<K: Hash + Eq, V>(cap: usize) -> RapidHashMap<K, V> {
+    HashMap::with_capacity_and_hasher(cap, rapidhash::fast::RandomState::default())
+}
+
+fn new_std_map<K: Hash + Eq, V>(cap: usize) -> StdHashMap<K, V> {
+    HashMap::with_capacity(cap)
+}
+
+// --- Test data generation ---
+
+static ATTRIBUTE_VALUES: [&str; 10] = [
+    "value1", "value2", "value3", "value4", "value5", "value6", "value7", "value8", "value9",
+    "value10",
+];
+
+/// Generate a set of KeyValue attribute vectors of a given size.
+fn generate_attribute_sets(num_attrs: usize, num_sets: usize) -> Vec<Vec<KeyValue>> {
+    let mut sets = Vec::with_capacity(num_sets);
+    for i in 0..num_sets {
+        let mut attrs = Vec::with_capacity(num_attrs);
+        for a in 0..num_attrs {
+            let val_idx = (i + a) % ATTRIBUTE_VALUES.len();
+            attrs.push(KeyValue::new(
+                format!("attribute{}", a + 1),
+                ATTRIBUTE_VALUES[val_idx],
+            ));
+        }
+        sets.push(attrs);
+    }
+    sets
+}
+
+// --- Generic benchmark functions ---
+
+fn bench_lookup_hit<S: BuildHasher + Default>(
+    map: &HashMap<Vec<KeyValue>, u64, S>,
+    keys: &[Vec<KeyValue>],
+) {
+    for key in keys {
+        std::hint::black_box(map.get(key));
+    }
+}
+
+fn bench_lookup_miss<S: BuildHasher + Default>(
+    map: &HashMap<Vec<KeyValue>, u64, S>,
+    miss_keys: &[Vec<KeyValue>],
+) {
+    for key in miss_keys {
+        std::hint::black_box(map.get(key));
+    }
+}
+
+fn bench_insert<S: BuildHasher + Clone>(hasher: &S, keys: &[Vec<KeyValue>], cap: usize) {
+    let mut map: HashMap<Vec<KeyValue>, u64, S> =
+        HashMap::with_capacity_and_hasher(cap, hasher.clone());
+    for key in keys {
+        map.insert(key.clone(), 1);
+    }
+    std::hint::black_box(&map);
+}
+
+fn bench_mixed_read_write<S: BuildHasher + Clone>(
+    hasher: &S,
+    keys: &[Vec<KeyValue>],
+    cap: usize,
+) {
+    // Simulates the ValueMap hot path: read-lock lookup, then occasional write-lock insert
+    let mut map: HashMap<Vec<KeyValue>, u64, S> =
+        HashMap::with_capacity_and_hasher(cap, hasher.clone());
+
+    for (i, key) in keys.iter().enumerate() {
+        // 80% lookups, 20% inserts (simulating warm cache)
+        if i % 5 == 0 || !map.contains_key(key) {
+            map.insert(key.clone(), 1);
+        } else {
+            if let Some(v) = map.get(key) {
+                std::hint::black_box(v);
+            }
+        }
+    }
+    std::hint::black_box(&map);
+}
+
+// --- Hash-only benchmark (pure hashing speed, no HashMap overhead) ---
+
+fn bench_hash_only<S: BuildHasher>(hasher: &S, keys: &[Vec<KeyValue>]) {
+    use std::hash::Hasher;
+    for key in keys {
+        let mut h = hasher.build_hasher();
+        key.hash(&mut h);
+        std::hint::black_box(h.finish());
+    }
+}
+
+// --- Criterion benchmarks ---
+
+fn hasher_comparison(c: &mut Criterion) {
+    let attr_counts = [2, 4, 8];
+    let num_entries = 1600; // Matches the metrics_counter benchmark cardinality
+
+    for &num_attrs in &attr_counts {
+        let keys = generate_attribute_sets(num_attrs, num_entries);
+        let miss_keys = generate_attribute_sets(num_attrs, 100)
+            .into_iter()
+            .map(|mut kv| {
+                // Modify to guarantee misses
+                if let Some(last) = kv.last_mut() {
+                    *last = KeyValue::new(last.key.clone(), "MISS_VALUE_NEVER_INSERTED");
+                }
+                kv
+            })
+            .collect::<Vec<_>>();
+
+        let group_name = format!("{num_attrs}_attrs");
+
+        // --- Hash-only (pure hashing, no HashMap) ---
+        {
+            let mut group = c.benchmark_group(format!("hash_only/{group_name}"));
+            group.warm_up_time(Duration::from_secs(1));
+            group.measurement_time(Duration::from_secs(3));
+
+            let ahash_state = ahash::RandomState::new();
+            let fold_state = foldhash::fast::RandomState::default();
+            let rapid_state = rapidhash::fast::RandomState::default();
+            let std_state = std::hash::RandomState::new();
+
+            group.bench_function("ahash", |b| b.iter(|| bench_hash_only(&ahash_state, &keys)));
+            group.bench_function("foldhash", |b| {
+                b.iter(|| bench_hash_only(&fold_state, &keys))
+            });
+            group.bench_function("rapidhash", |b| {
+                b.iter(|| bench_hash_only(&rapid_state, &keys))
+            });
+            group.bench_function("std", |b| b.iter(|| bench_hash_only(&std_state, &keys)));
+            group.finish();
+        }
+
+        // --- Lookup hit ---
+        {
+            let mut group = c.benchmark_group(format!("lookup_hit/{group_name}"));
+            group.warm_up_time(Duration::from_secs(1));
+            group.measurement_time(Duration::from_secs(3));
+
+            let mut ahash_map = new_ahash_map(num_entries);
+            let mut fold_map = new_foldhash_map(num_entries);
+            let mut rapid_map = new_rapidhash_map(num_entries);
+            let mut std_map = new_std_map(num_entries);
+            for key in &keys {
+                ahash_map.insert(key.clone(), 1);
+                fold_map.insert(key.clone(), 1);
+                rapid_map.insert(key.clone(), 1);
+                std_map.insert(key.clone(), 1);
+            }
+
+            group.bench_function("ahash", |b| b.iter(|| bench_lookup_hit(&ahash_map, &keys)));
+            group.bench_function("foldhash", |b| {
+                b.iter(|| bench_lookup_hit(&fold_map, &keys))
+            });
+            group.bench_function("rapidhash", |b| {
+                b.iter(|| bench_lookup_hit(&rapid_map, &keys))
+            });
+            group.bench_function("std", |b| b.iter(|| bench_lookup_hit(&std_map, &keys)));
+            group.finish();
+        }
+
+        // --- Lookup miss ---
+        {
+            let mut group = c.benchmark_group(format!("lookup_miss/{group_name}"));
+            group.warm_up_time(Duration::from_secs(1));
+            group.measurement_time(Duration::from_secs(3));
+
+            let mut ahash_map = new_ahash_map(num_entries);
+            let mut fold_map = new_foldhash_map(num_entries);
+            let mut rapid_map = new_rapidhash_map(num_entries);
+            let mut std_map = new_std_map(num_entries);
+            for key in &keys {
+                ahash_map.insert(key.clone(), 1);
+                fold_map.insert(key.clone(), 1);
+                rapid_map.insert(key.clone(), 1);
+                std_map.insert(key.clone(), 1);
+            }
+
+            group.bench_function("ahash", |b| {
+                b.iter(|| bench_lookup_miss(&ahash_map, &miss_keys))
+            });
+            group.bench_function("foldhash", |b| {
+                b.iter(|| bench_lookup_miss(&fold_map, &miss_keys))
+            });
+            group.bench_function("rapidhash", |b| {
+                b.iter(|| bench_lookup_miss(&rapid_map, &miss_keys))
+            });
+            group.bench_function("std", |b| {
+                b.iter(|| bench_lookup_miss(&std_map, &miss_keys))
+            });
+            group.finish();
+        }
+
+        // --- Insert ---
+        {
+            let mut group = c.benchmark_group(format!("insert/{group_name}"));
+            group.warm_up_time(Duration::from_secs(1));
+            group.measurement_time(Duration::from_secs(3));
+
+            let ahash_state = ahash::RandomState::new();
+            let fold_state = foldhash::fast::RandomState::default();
+            let rapid_state = rapidhash::fast::RandomState::default();
+            let std_state = std::hash::RandomState::new();
+
+            group.bench_function("ahash", |b| {
+                b.iter(|| bench_insert(&ahash_state, &keys, num_entries))
+            });
+            group.bench_function("foldhash", |b| {
+                b.iter(|| bench_insert(&fold_state, &keys, num_entries))
+            });
+            group.bench_function("rapidhash", |b| {
+                b.iter(|| bench_insert(&rapid_state, &keys, num_entries))
+            });
+            group.bench_function("std", |b| {
+                b.iter(|| bench_insert(&std_state, &keys, num_entries))
+            });
+            group.finish();
+        }
+
+        // --- Mixed read/write (simulates ValueMap hot path) ---
+        {
+            let mut group = c.benchmark_group(format!("mixed_rw/{group_name}"));
+            group.warm_up_time(Duration::from_secs(1));
+            group.measurement_time(Duration::from_secs(3));
+
+            let ahash_state = ahash::RandomState::new();
+            let fold_state = foldhash::fast::RandomState::default();
+            let rapid_state = rapidhash::fast::RandomState::default();
+            let std_state = std::hash::RandomState::new();
+
+            group.bench_function("ahash", |b| {
+                b.iter(|| bench_mixed_read_write(&ahash_state, &keys, num_entries))
+            });
+            group.bench_function("foldhash", |b| {
+                b.iter(|| bench_mixed_read_write(&fold_state, &keys, num_entries))
+            });
+            group.bench_function("rapidhash", |b| {
+                b.iter(|| bench_mixed_read_write(&rapid_state, &keys, num_entries))
+            });
+            group.bench_function("std", |b| {
+                b.iter(|| bench_mixed_read_write(&std_state, &keys, num_entries))
+            });
+            group.finish();
+        }
+    }
+}
+
+criterion_group! {
+    name = benches;
+    config = Criterion::default()
+        .warm_up_time(Duration::from_secs(1))
+        .measurement_time(Duration::from_secs(3));
+    targets = hasher_comparison
+}
+criterion_main!(benches);
diff --git a/opentelemetry-sdk/src/metrics/internal/mod.rs b/opentelemetry-sdk/src/metrics/internal/mod.rs
@@ -9,7 +9,7 @@ use core::fmt;
 #[cfg(not(target_has_atomic = "64"))]
 use portable_atomic::{AtomicI64, AtomicU64};
 use std::cmp::min;
-use std::collections::{HashMap, HashSet};
+use std::collections::HashSet;
 use std::mem::swap;
 use std::ops::{Add, AddAssign, DerefMut, Sub};
 use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
@@ -24,6 +24,23 @@ use opentelemetry::{otel_warn, KeyValue};
 use super::data::{AggregatedMetrics, MetricData};
 use super::pipeline::DEFAULT_CARDINALITY_LIMIT;
 
+#[cfg(feature = "metrics-use-rapidhash")]
+type HashMap<K, V> = std::collections::HashMap<K, V, rapidhash::fast::RandomState>;
+#[cfg(not(feature = "metrics-use-rapidhash"))]
+type HashMap<K, V> = std::collections::HashMap<K, V>;
+
+#[cfg(feature = "metrics-use-rapidhash")]
+fn new_hashmap<K, V>(capacity: usize) -> HashMap<K, V> {
+    std::collections::HashMap::with_capacity_and_hasher(
+        capacity,
+        rapidhash::fast::RandomState::default(),
+    )
+}
+#[cfg(not(feature = "metrics-use-rapidhash"))]
+fn new_hashmap<K, V>(capacity: usize) -> HashMap<K, V> {
+    std::collections::HashMap::with_capacity(capacity)
+}
+
 // TODO Replace it with LazyLock once it is stable
 pub(crate) static STREAM_OVERFLOW_ATTRIBUTES: OnceLock<Vec<KeyValue>> = OnceLock::new();
 
@@ -85,7 +102,7 @@ where
 {
     fn new(config: A::InitConfig, cardinality_limit: usize) -> Self {
         ValueMap {
-            trackers: RwLock::new(HashMap::with_capacity(
+            trackers: RwLock::new(new_hashmap(
                 1 + min(DEFAULT_CARDINALITY_LIMIT, cardinality_limit),
             )),
             trackers_for_collect: OnceLock::new(),
@@ -100,7 +117,7 @@ where
     #[inline]
     fn trackers_for_collect(&self) -> &RwLock<HashMap<Vec<KeyValue>, Arc<A>>> {
         self.trackers_for_collect.get_or_init(|| {
-            RwLock::new(HashMap::with_capacity(
+            RwLock::new(new_hashmap(
                 1 + min(DEFAULT_CARDINALITY_LIMIT, self.cardinality_limit),
             ))
         })
