use core::cell::RefCell;
use core::fmt;
use critical_section::Mutex;
use portable_atomic::{AtomicU64, Ordering};
use crate::config::LABEL_VALUE_LEN;
use crate::counter::Counter;
use crate::erased::{ErasedCounterVec, ErasedGaugeVec, ErasedHistogramVec};
#[cfg(feature = "consistent-histograms")]
use crate::erased::{HistogramSnapshot, HistogramSnapshotError, snapshot_bucket_prefix};
use crate::escape::valid_label_name;
use crate::gauge::Gauge;
#[cfg(feature = "float")]
use crate::histogram::validate_f64_bounds;
use crate::histogram::validate_u64_bounds;
use crate::labels::{LabelBlock, build_block};
use crate::value::Value;
type KeyMap<const N: usize, const V: usize> = Mutex<RefCell<heapless::Vec<LabelBlock<V>, N>>>;
const fn str_eq(a: &str, b: &str) -> bool {
let a = a.as_bytes();
let b = b.as_bytes();
if a.len() != b.len() {
return false;
}
let mut i = 0;
while i < a.len() {
if a[i] != b[i] {
return false;
}
i += 1;
}
true
}
const fn validate_label_names<const K: usize>(names: &'static [&'static str; K], histogram: bool) {
let mut i = 0;
while i < K {
assert!(valid_label_name(names[i]), "embeprom: invalid label name");
assert!(
!(histogram && str_eq(names[i], "le")),
"embeprom: histogram label name `le` is reserved"
);
let mut j = 0;
while j < i {
assert!(
!str_eq(names[i], names[j]),
"embeprom: duplicate label name"
);
j += 1;
}
i += 1;
}
}
fn slot_index<const N: usize, const K: usize, const V: usize>(
keys: &KeyMap<N, V>,
names: &'static [&'static str; K],
values: &[&str; K],
) -> Option<usize> {
let block = build_block::<K, V>(names, values).ok()?;
critical_section::with(|cs| {
let mut keys = keys.borrow_ref_mut(cs);
if let Some(i) = keys.iter().position(|k| *k == block) {
return Some(i);
}
keys.push(block).ok().map(|()| keys.len() - 1)
})
}
fn write_labels_at<const N: usize, const V: usize>(
keys: &KeyMap<N, V>,
s: usize,
out: &mut dyn fmt::Write,
) -> fmt::Result {
let block = critical_section::with(|cs| keys.borrow_ref(cs)[s].clone());
out.write_str(&block)
}
fn series_count_of<const N: usize, const V: usize>(keys: &KeyMap<N, V>) -> usize {
critical_section::with(|cs| keys.borrow_ref(cs).len())
}
#[derive(Debug, Clone, Copy)]
pub struct CounterSeries<'a> {
counter: Option<&'a Counter>,
}
impl CounterSeries<'_> {
fn metric(counter: &Counter) -> CounterSeries<'_> {
CounterSeries {
counter: Some(counter),
}
}
const fn sink() -> Self {
Self { counter: None }
}
#[inline]
pub fn inc(&self) {
if let Some(counter) = self.counter {
counter.inc();
}
}
#[inline]
pub fn inc_by(&self, n: u64) {
if let Some(counter) = self.counter {
counter.inc_by(n);
}
}
#[inline]
pub fn get(&self) -> u64 {
self.counter.map_or(0, Counter::get)
}
#[inline]
pub fn reset(&self) {
if let Some(counter) = self.counter {
counter.reset();
}
}
}
#[derive(Debug, Clone, Copy)]
pub struct GaugeSeries<'a> {
gauge: Option<&'a Gauge>,
}
impl GaugeSeries<'_> {
fn metric(gauge: &Gauge) -> GaugeSeries<'_> {
GaugeSeries { gauge: Some(gauge) }
}
const fn sink() -> Self {
Self { gauge: None }
}
#[inline]
pub fn set(&self, value: i64) {
if let Some(gauge) = self.gauge {
gauge.set(value);
}
}
#[inline]
pub fn add(&self, delta: i64) {
if let Some(gauge) = self.gauge {
gauge.add(delta);
}
}
#[inline]
pub fn sub(&self, delta: i64) {
if let Some(gauge) = self.gauge {
gauge.sub(delta);
}
}
#[inline]
pub fn inc(&self) {
if let Some(gauge) = self.gauge {
gauge.inc();
}
}
#[inline]
pub fn dec(&self) {
if let Some(gauge) = self.gauge {
gauge.dec();
}
}
#[inline]
pub fn get(&self) -> i64 {
self.gauge.map_or(0, Gauge::get)
}
}
pub struct CounterVec<const N: usize, const K: usize = 1, const V: usize = LABEL_VALUE_LEN> {
names: &'static [&'static str; K],
keys: KeyMap<N, V>,
vals: [Counter; N],
}
impl<const N: usize, const K: usize, const V: usize> CounterVec<N, K, V> {
pub const fn new(names: &'static [&'static str; K]) -> Self {
validate_label_names(names, false);
Self {
names,
keys: Mutex::new(RefCell::new(heapless::Vec::new())),
vals: [const { Counter::new() }; N],
}
}
pub fn with(&self, values: &[&str; K]) -> CounterSeries<'_> {
match slot_index(&self.keys, self.names, values) {
Some(idx) => CounterSeries::metric(&self.vals[idx]),
None => CounterSeries::sink(),
}
}
#[inline]
pub fn inc(&self, values: &[&str; K]) {
self.with(values).inc();
}
#[inline]
pub fn inc_by(&self, values: &[&str; K], n: u64) {
self.with(values).inc_by(n);
}
pub fn series_count(&self) -> usize {
series_count_of(&self.keys)
}
}
impl<const N: usize, const K: usize, const V: usize> ErasedCounterVec for CounterVec<N, K, V> {
fn series_count(&self) -> usize {
CounterVec::series_count(self)
}
fn write_labels(&self, s: usize, out: &mut dyn fmt::Write) -> fmt::Result {
write_labels_at(&self.keys, s, out)
}
fn value(&self, s: usize) -> u64 {
self.vals[s].get()
}
}
pub struct GaugeVec<const N: usize, const K: usize = 1, const V: usize = LABEL_VALUE_LEN> {
names: &'static [&'static str; K],
keys: KeyMap<N, V>,
vals: [Gauge; N],
}
impl<const N: usize, const K: usize, const V: usize> GaugeVec<N, K, V> {
pub const fn new(names: &'static [&'static str; K]) -> Self {
validate_label_names(names, false);
Self {
names,
keys: Mutex::new(RefCell::new(heapless::Vec::new())),
vals: [const { Gauge::new(0) }; N],
}
}
pub fn with(&self, values: &[&str; K]) -> GaugeSeries<'_> {
match slot_index(&self.keys, self.names, values) {
Some(idx) => GaugeSeries::metric(&self.vals[idx]),
None => GaugeSeries::sink(),
}
}
#[inline]
pub fn set(&self, values: &[&str; K], v: i64) {
self.with(values).set(v);
}
#[inline]
pub fn add(&self, values: &[&str; K], d: i64) {
self.with(values).add(d);
}
pub fn series_count(&self) -> usize {
series_count_of(&self.keys)
}
}
impl<const N: usize, const K: usize, const V: usize> ErasedGaugeVec for GaugeVec<N, K, V> {
fn series_count(&self) -> usize {
GaugeVec::series_count(self)
}
fn write_labels(&self, s: usize, out: &mut dyn fmt::Write) -> fmt::Result {
write_labels_at(&self.keys, s, out)
}
fn value(&self, s: usize) -> Value {
Value::I64(self.vals[s].get())
}
}
#[derive(Clone, Copy)]
struct IntHistMetric<'a> {
bounds: &'static [u64],
buckets: &'a [AtomicU64],
sum: &'a AtomicU64,
count: &'a AtomicU64,
}
#[derive(Clone, Copy)]
pub struct IntHistSeries<'a> {
metric: Option<IntHistMetric<'a>>,
}
impl<'a> IntHistSeries<'a> {
fn bound(
bounds: &'static [u64],
buckets: &'a [AtomicU64],
sum: &'a AtomicU64,
count: &'a AtomicU64,
) -> Self {
Self {
metric: Some(IntHistMetric {
bounds,
buckets,
sum,
count,
}),
}
}
const fn sink() -> Self {
Self { metric: None }
}
#[inline]
pub fn observe(&self, v: u64) {
let Some(metric) = self.metric else {
return;
};
#[cfg(feature = "consistent-histograms")]
critical_section::with(|_cs| Self::observe_inner(metric, v));
#[cfg(not(feature = "consistent-histograms"))]
Self::observe_inner(metric, v);
}
#[inline]
fn observe_inner(metric: IntHistMetric<'_>, v: u64) {
if let Some(i) = metric.bounds.iter().position(|bound| v <= *bound) {
metric.buckets[i].fetch_add(1, Ordering::Relaxed);
}
metric.sum.fetch_add(v, Ordering::Relaxed);
metric.count.fetch_add(1, Ordering::Relaxed);
}
}
pub struct IntHistogramVec<
const N: usize,
const B: usize,
const K: usize = 1,
const V: usize = LABEL_VALUE_LEN,
> {
names: &'static [&'static str; K],
bounds: &'static [u64],
keys: KeyMap<N, V>,
buckets: [[AtomicU64; B]; N],
sums: [AtomicU64; N],
counts: [AtomicU64; N],
}
impl<const N: usize, const B: usize, const K: usize, const V: usize> IntHistogramVec<N, B, K, V> {
pub const fn new(names: &'static [&'static str; K], bounds: &'static [u64]) -> Self {
validate_label_names(names, true);
validate_u64_bounds::<B>(bounds);
Self {
names,
bounds,
keys: Mutex::new(RefCell::new(heapless::Vec::new())),
buckets: [const { [const { AtomicU64::new(0) }; B] }; N],
sums: [const { AtomicU64::new(0) }; N],
counts: [const { AtomicU64::new(0) }; N],
}
}
pub fn with(&self, values: &[&str; K]) -> IntHistSeries<'_> {
match slot_index(&self.keys, self.names, values) {
Some(idx) => IntHistSeries::bound(
self.bounds,
&self.buckets[idx],
&self.sums[idx],
&self.counts[idx],
),
None => IntHistSeries::sink(),
}
}
#[inline]
pub fn observe(&self, values: &[&str; K], v: u64) {
self.with(values).observe(v);
}
pub fn series_count(&self) -> usize {
series_count_of(&self.keys)
}
}
impl<const N: usize, const B: usize, const K: usize, const V: usize> ErasedHistogramVec
for IntHistogramVec<N, B, K, V>
{
fn bucket_count(&self) -> usize {
B
}
fn bound(&self, b: usize) -> Value {
Value::U64(self.bounds[b])
}
fn series_count(&self) -> usize {
IntHistogramVec::series_count(self)
}
fn write_labels(&self, s: usize, out: &mut dyn fmt::Write) -> fmt::Result {
write_labels_at(&self.keys, s, out)
}
fn bucket(&self, s: usize, b: usize) -> u64 {
self.buckets[s][b].load(Ordering::Relaxed)
}
fn total_count(&self, s: usize) -> u64 {
self.counts[s].load(Ordering::Relaxed)
}
fn sum(&self, s: usize) -> Value {
Value::U64(self.sums[s].load(Ordering::Relaxed))
}
#[cfg(feature = "consistent-histograms")]
fn snapshot<'a>(
&self,
s: usize,
buckets: &'a mut [u64],
) -> Result<HistogramSnapshot<'a>, HistogramSnapshotError> {
let buckets = snapshot_bucket_prefix(buckets, B)?;
critical_section::with(|_cs| {
for (snapshot_bucket, bucket) in buckets.iter_mut().zip(&self.buckets[s]) {
*snapshot_bucket = bucket.load(Ordering::Relaxed);
}
Ok(HistogramSnapshot {
buckets,
sum: Value::U64(self.sums[s].load(Ordering::Relaxed)),
count: self.counts[s].load(Ordering::Relaxed),
})
})
}
}
#[cfg(feature = "float")]
#[derive(Clone, Copy)]
struct HistMetric<'a> {
bounds: &'static [f64],
buckets: &'a [AtomicU64],
sum: &'a portable_atomic::AtomicF64,
count: &'a AtomicU64,
}
#[cfg(feature = "float")]
#[derive(Clone, Copy)]
pub struct HistSeries<'a> {
metric: Option<HistMetric<'a>>,
}
#[cfg(feature = "float")]
impl<'a> HistSeries<'a> {
fn bound(
bounds: &'static [f64],
buckets: &'a [AtomicU64],
sum: &'a portable_atomic::AtomicF64,
count: &'a AtomicU64,
) -> Self {
Self {
metric: Some(HistMetric {
bounds,
buckets,
sum,
count,
}),
}
}
const fn sink() -> Self {
Self { metric: None }
}
#[inline]
pub fn observe(&self, v: f64) {
let Some(metric) = self.metric else {
return;
};
#[cfg(feature = "consistent-histograms")]
critical_section::with(|_cs| Self::observe_inner(metric, v));
#[cfg(not(feature = "consistent-histograms"))]
Self::observe_inner(metric, v);
}
#[inline]
fn observe_inner(metric: HistMetric<'_>, v: f64) {
if let Some(i) = metric.bounds.iter().position(|bound| v <= *bound) {
metric.buckets[i].fetch_add(1, Ordering::Relaxed);
}
metric.sum.fetch_add(v, Ordering::Relaxed);
metric.count.fetch_add(1, Ordering::Relaxed);
}
}
#[cfg(feature = "float")]
pub struct HistogramVec<
const N: usize,
const B: usize,
const K: usize = 1,
const V: usize = LABEL_VALUE_LEN,
> {
names: &'static [&'static str; K],
bounds: &'static [f64],
keys: KeyMap<N, V>,
buckets: [[AtomicU64; B]; N],
sums: [portable_atomic::AtomicF64; N],
counts: [AtomicU64; N],
}
#[cfg(feature = "float")]
impl<const N: usize, const B: usize, const K: usize, const V: usize> HistogramVec<N, B, K, V> {
pub const fn new(names: &'static [&'static str; K], bounds: &'static [f64]) -> Self {
validate_label_names(names, true);
validate_f64_bounds::<B>(bounds);
Self {
names,
bounds,
keys: Mutex::new(RefCell::new(heapless::Vec::new())),
buckets: [const { [const { AtomicU64::new(0) }; B] }; N],
sums: [const { portable_atomic::AtomicF64::new(0.0) }; N],
counts: [const { AtomicU64::new(0) }; N],
}
}
pub fn with(&self, values: &[&str; K]) -> HistSeries<'_> {
match slot_index(&self.keys, self.names, values) {
Some(idx) => HistSeries::bound(
self.bounds,
&self.buckets[idx],
&self.sums[idx],
&self.counts[idx],
),
None => HistSeries::sink(),
}
}
#[inline]
pub fn observe(&self, values: &[&str; K], v: f64) {
self.with(values).observe(v);
}
pub fn series_count(&self) -> usize {
series_count_of(&self.keys)
}
}
#[cfg(feature = "float")]
impl<const N: usize, const B: usize, const K: usize, const V: usize> ErasedHistogramVec
for HistogramVec<N, B, K, V>
{
fn bucket_count(&self) -> usize {
B
}
fn bound(&self, b: usize) -> Value {
Value::F64(self.bounds[b])
}
fn series_count(&self) -> usize {
HistogramVec::series_count(self)
}
fn write_labels(&self, s: usize, out: &mut dyn fmt::Write) -> fmt::Result {
write_labels_at(&self.keys, s, out)
}
fn bucket(&self, s: usize, b: usize) -> u64 {
self.buckets[s][b].load(Ordering::Relaxed)
}
fn total_count(&self, s: usize) -> u64 {
self.counts[s].load(Ordering::Relaxed)
}
fn sum(&self, s: usize) -> Value {
Value::F64(self.sums[s].load(Ordering::Relaxed))
}
#[cfg(feature = "consistent-histograms")]
fn snapshot<'a>(
&self,
s: usize,
buckets: &'a mut [u64],
) -> Result<HistogramSnapshot<'a>, HistogramSnapshotError> {
let buckets = snapshot_bucket_prefix(buckets, B)?;
critical_section::with(|_cs| {
for (snapshot_bucket, bucket) in buckets.iter_mut().zip(&self.buckets[s]) {
*snapshot_bucket = bucket.load(Ordering::Relaxed);
}
Ok(HistogramSnapshot {
buckets,
sum: Value::F64(self.sums[s].load(Ordering::Relaxed)),
count: self.counts[s].load(Ordering::Relaxed),
})
})
}
}
#[cfg(test)]
mod tests {
use super::*;
static REASON: [&str; 1] = ["reason"];
static PEER: [&str; 1] = ["peer"];
fn labels_of<E: ErasedCounterVec>(v: &E, s: usize) -> heapless::String<64> {
let mut out = heapless::String::<64>::new();
v.write_labels(s, &mut out).unwrap();
out
}
#[test]
fn counter_vec_creates_and_increments_series() {
let cv: CounterVec<4> = CounterVec::new(&REASON);
cv.inc(&["timeout"]);
cv.inc_by(&["timeout"], 2);
cv.inc(&["auth_fail"]);
assert_eq!(cv.series_count(), 2);
assert_eq!(cv.with(&["timeout"]).get(), 3);
assert_eq!(cv.with(&["auth_fail"]).get(), 1);
assert_eq!(labels_of(&cv, 0), "reason=\"timeout\"");
}
#[test]
#[should_panic(expected = "invalid label name")]
fn counter_vec_rejects_invalid_label_names_at_runtime() {
let _ = CounterVec::<1, 1>::new(&["not-valid"]);
}
#[test]
#[should_panic(expected = "duplicate label name")]
fn counter_vec_rejects_duplicate_label_names_at_runtime() {
let _ = CounterVec::<1, 2>::new(&["kind", "kind"]);
}
#[test]
fn cached_counter_series_can_be_reused_for_hot_path_updates() {
let cv: CounterVec<4> = CounterVec::new(&REASON);
let timeout = cv.with(&["timeout"]);
timeout.inc();
timeout.inc_by(4);
assert_eq!(timeout.get(), 5);
assert_eq!(cv.series_count(), 1);
}
#[test]
fn counter_vec_drops_excess_series_but_keeps_existing_ones_updating() {
let cv: CounterVec<2> = CounterVec::new(&REASON);
cv.inc(&["a"]);
cv.inc(&["b"]);
let sink = cv.with(&["c"]); sink.inc_by(100);
assert_eq!(sink.get(), 0);
cv.inc(&["a"]); assert_eq!(cv.series_count(), 2);
assert_eq!(cv.with(&["a"]).get(), 2);
}
#[test]
fn counter_vec_drops_oversized_label_values_without_affecting_existing_series() {
let cv: CounterVec<4, 1, 20> = CounterVec::new(&REASON);
cv.inc(&["ok"]);
let sink = cv.with(&["this value is far too long to fit"]);
sink.inc();
assert_eq!(sink.get(), 0);
assert_eq!(cv.series_count(), 1);
assert_eq!(cv.with(&["ok"]).get(), 1);
}
#[test]
fn gauge_vec_creates_and_sets_series() {
let gv: GaugeVec<4> = GaugeVec::new(&PEER);
gv.set(&["ap-1"], 10);
gv.add(&["ap-1"], -3);
gv.set(&["ap-2"], 5);
assert_eq!(gv.with(&["ap-1"]).get(), 7);
assert_eq!(gv.with(&["ap-2"]).get(), 5);
assert_eq!(gv.series_count(), 2);
}
#[test]
fn gauge_vec_returns_zero_reading_sink_when_full() {
let gv: GaugeVec<1> = GaugeVec::new(&PEER);
gv.set(&["ap-1"], 7);
let sink = gv.with(&["ap-2"]);
sink.set(99);
sink.inc();
assert_eq!(sink.get(), 0);
assert_eq!(gv.with(&["ap-1"]).get(), 7);
assert_eq!(gv.series_count(), 1);
}
#[test]
fn int_histogram_vec_tracks_independent_series() {
let hv: IntHistogramVec<4, 2> = IntHistogramVec::new(&PEER, &[100, 1000]);
hv.observe(&["ap-1"], 50);
hv.observe(&["ap-1"], 500);
hv.observe(&["ap-2"], 2000);
assert_eq!(hv.series_count(), 2);
assert_eq!(hv.bucket(0, 0), 1);
assert_eq!(hv.bucket(0, 1), 1);
assert_eq!(hv.total_count(0), 2);
assert_eq!(hv.sum(0), Value::U64(550));
assert_eq!(hv.bucket(1, 0), 0);
assert_eq!(hv.bucket(1, 1), 0);
assert_eq!(hv.total_count(1), 1); }
#[test]
fn cached_histogram_series_can_be_reused_for_hot_path_observations() {
let hv: IntHistogramVec<4, 2> = IntHistogramVec::new(&PEER, &[100, 1000]);
let ap = hv.with(&["ap-1"]);
ap.observe(50);
ap.observe(500);
assert_eq!(hv.series_count(), 1);
assert_eq!(hv.bucket(0, 0), 1);
assert_eq!(hv.bucket(0, 1), 1);
assert_eq!(hv.total_count(0), 2);
}
#[test]
fn int_histogram_vec_sink_discards_observations_when_full() {
let hv: IntHistogramVec<1, 2> = IntHistogramVec::new(&PEER, &[100, 1000]);
hv.observe(&["ap-1"], 50);
let sink = hv.with(&["ap-2"]);
sink.observe(500);
assert_eq!(hv.series_count(), 1);
assert_eq!(hv.total_count(0), 1);
assert_eq!(hv.sum(0), Value::U64(50));
}
#[test]
#[should_panic(expected = "histogram bounds must be strictly increasing")]
fn int_histogram_vec_rejects_invalid_bounds() {
let _ = IntHistogramVec::<1, 2>::new(&PEER, &[1000, 100]);
}
#[test]
#[should_panic(expected = "histogram label name `le` is reserved")]
fn int_histogram_vec_rejects_the_generated_bucket_label_name() {
let _ = IntHistogramVec::<1, 1>::new(&["le"], &[100]);
}
#[cfg(feature = "float")]
#[test]
fn histogram_vec_tracks_independent_series() {
let hv: HistogramVec<4, 2> = HistogramVec::new(&PEER, &[0.5, 5.0]);
hv.observe(&["ap-1"], 0.25);
hv.observe(&["ap-1"], 2.0);
assert_eq!(hv.bucket(0, 0), 1);
assert_eq!(hv.bucket(0, 1), 1);
assert_eq!(hv.sum(0), Value::F64(2.25));
}
#[cfg(feature = "float")]
#[test]
fn histogram_vec_routes_nan_only_to_the_implicit_infinite_bucket() {
let hv: HistogramVec<1, 2> = HistogramVec::new(&PEER, &[0.5, 5.0]);
hv.observe(&["ap-1"], f64::NAN);
assert_eq!(hv.bucket(0, 0), 0);
assert_eq!(hv.bucket(0, 1), 0);
assert_eq!(hv.total_count(0), 1);
assert!(matches!(hv.sum(0), Value::F64(sum) if sum.is_nan()));
}
#[cfg(feature = "float")]
#[test]
fn float_histogram_vec_sink_discards_observations_when_full() {
let hv: HistogramVec<1, 2> = HistogramVec::new(&PEER, &[0.5, 5.0]);
hv.observe(&["ap-1"], 0.25);
let sink = hv.with(&["ap-2"]);
sink.observe(2.0);
assert_eq!(hv.series_count(), 1);
assert_eq!(hv.total_count(0), 1);
assert_eq!(hv.sum(0), Value::F64(0.25));
}
}