use std::{
collections::{BTreeMap, BTreeSet},
fmt::{self, Write},
sync::Mutex,
};
use serde::{Deserialize, Deserializer, Serialize, Serializer, ser::SerializeStruct};
use thiserror::Error;
use crate::result::{ClassifyError, ErrorKind};
pub const MAX_METRIC_NAME_LENGTH: usize = 128;
pub const MAX_METRIC_LABELS: usize = 16;
pub const MAX_METRIC_LABEL_KEY_LENGTH: usize = 64;
pub const MAX_METRIC_LABEL_VALUE_LENGTH: usize = 65_536;
pub const DEFAULT_MAX_METRIC_LABEL_VALUE_LENGTH: usize = 256;
pub const DEFAULT_MAX_METRIC_SERIES: usize = 10_000;
pub const DEFAULT_MAX_METRIC_SERIES_PER_METRIC: usize = 1_000;
pub const DEFAULT_HISTOGRAM_BUCKETS: &[f64] = &[
0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0,
];
pub const MAX_HISTOGRAM_BUCKETS: usize = 128;
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
pub enum MetricKind {
Counter,
Gauge,
Histogram,
}
#[derive(Clone, PartialEq)]
#[non_exhaustive]
pub struct MetricSample {
name: String,
kind: MetricKind,
value: f64,
labels: Vec<(String, String)>,
count: Option<u64>,
buckets: Vec<(f64, u64)>,
}
impl Serialize for MetricSample {
fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
let include_count = !serializer.is_human_readable() || self.count.is_some();
let include_buckets = !serializer.is_human_readable() || !self.buckets.is_empty();
let mut sample = serializer.serialize_struct(
"MetricSample",
4 + usize::from(include_count) + usize::from(include_buckets),
)?;
sample.serialize_field("name", &self.name)?;
sample.serialize_field("kind", &self.kind)?;
sample.serialize_field("value", &self.value)?;
sample.serialize_field("labels", &self.labels)?;
if include_count {
sample.serialize_field("count", &self.count)?;
}
if include_buckets {
sample.serialize_field("buckets", &self.buckets)?;
}
sample.end()
}
}
impl fmt::Debug for MetricSample {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("MetricSample")
.field("name", &self.name)
.field("kind", &self.kind)
.field("value", &self.value)
.field("label_count", &self.labels.len())
.field("count", &self.count)
.finish()
}
}
impl MetricSample {
pub fn new(
name: impl Into<String>,
kind: MetricKind,
value: f64,
) -> Result<Self, MetricsError> {
if kind == MetricKind::Histogram {
return Err(MetricsError::InvalidHistogram);
}
validate_metric_kind_value(kind, value)?;
let name = validated_metric_name(name, kind)?;
Ok(Self::from_valid_parts(name, kind, value))
}
fn from_valid_parts(name: String, kind: MetricKind, value: f64) -> Self {
Self {
name,
kind,
value,
labels: Vec::new(),
count: None,
buckets: Vec::new(),
}
}
pub fn counter(name: impl Into<String>, value: u64) -> Result<Self, MetricsError> {
let name = validated_metric_name(name, MetricKind::Counter)?;
Ok(Self::from_valid_parts(
name,
MetricKind::Counter,
value as f64,
))
}
pub fn gauge(name: impl Into<String>, value: f64) -> Result<Self, MetricsError> {
Self::new(name, MetricKind::Gauge, value)
}
pub fn histogram(
name: impl Into<String>,
count: u64,
sum: f64,
buckets: Vec<(f64, u64)>,
) -> Result<Self, MetricsError> {
validate_metric_kind_value(MetricKind::Histogram, sum)?;
validate_histogram_buckets(buckets.iter().map(|(bound, _)| *bound))?;
if (count == 0 && sum != 0.0)
|| buckets.iter().any(|(_, value)| *value > count)
|| buckets.windows(2).any(|pair| pair[0].1 > pair[1].1)
{
return Err(MetricsError::InvalidHistogram);
}
let mut sample = Self::from_valid_parts(
validated_metric_name(name, MetricKind::Histogram)?,
MetricKind::Histogram,
sum,
);
sample.count = Some(count);
sample.buckets = buckets;
Ok(sample)
}
pub fn with_label(
mut self,
key: impl Into<String>,
value: impl Into<String>,
) -> Result<Self, MetricsError> {
self.insert_label(key.into(), value.into())?;
Ok(self)
}
fn insert_label(&mut self, key: String, value: String) -> Result<(), MetricsError> {
let key = validated_metric_label_key(key)?;
let value = validated_metric_label_value(value)?;
if self.kind == MetricKind::Histogram && key == "le" {
return Err(MetricsError::ReservedHistogramLabel);
}
match self
.labels
.binary_search_by(|(existing, _)| existing.cmp(&key))
{
Ok(index) if value.is_empty() => {
self.labels.remove(index);
}
Ok(index) => self.labels[index].1 = value,
Err(_) if value.is_empty() => {}
Err(index) => {
if self.labels.len() >= MAX_METRIC_LABELS {
return Err(MetricsError::TooManyLabels {
max: MAX_METRIC_LABELS,
});
}
self.labels.insert(index, (key, value));
}
}
Ok(())
}
pub fn with_labels(mut self, labels: MetricLabels) -> Result<Self, MetricsError> {
validate_metric_kind_labels(self.kind, &labels)?;
self.labels = labels.into_vec();
Ok(self)
}
#[must_use]
pub fn buckets(&self) -> &[(f64, u64)] {
&self.buckets
}
#[must_use]
pub fn name(&self) -> &str {
&self.name
}
#[must_use]
pub const fn kind(&self) -> MetricKind {
self.kind
}
#[must_use]
pub const fn value(&self) -> f64 {
self.value
}
#[must_use]
pub const fn count(&self) -> Option<u64> {
self.count
}
#[must_use]
pub fn labels(&self) -> &[(String, String)] {
&self.labels
}
}
impl<'de> Deserialize<'de> for MetricSample {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct MetricSampleWire {
name: String,
kind: MetricKind,
value: f64,
#[serde(default)]
labels: MetricLabels,
#[serde(default)]
count: Option<u64>,
#[serde(default)]
buckets: Vec<(f64, u64)>,
}
let wire = MetricSampleWire::deserialize(deserializer)?;
let sample = match (wire.kind, wire.count) {
(MetricKind::Histogram, Some(count)) => {
Self::histogram(wire.name, count, wire.value, wire.buckets)
}
(MetricKind::Histogram, None) => Err(MetricsError::InvalidHistogram),
(_, None) if wire.buckets.is_empty() => Self::new(wire.name, wire.kind, wire.value),
_ => Err(MetricsError::InvalidHistogram),
}
.map_err(serde::de::Error::custom)?;
sample
.with_labels(wire.labels)
.map_err(serde::de::Error::custom)
}
}
#[derive(Clone, Default, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[non_exhaustive]
pub struct MetricLabels(Vec<(String, String)>);
impl fmt::Debug for MetricLabels {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("MetricLabels")
.field("label_count", &self.0.len())
.finish_non_exhaustive()
}
}
impl MetricLabels {
pub fn new(
labels: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
) -> Result<Self, MetricsError> {
let mut normalized = BTreeMap::<String, String>::new();
for (index, (key, value)) in labels.into_iter().enumerate() {
if index >= MAX_METRIC_LABELS {
return Err(MetricsError::TooManyLabels {
max: MAX_METRIC_LABELS,
});
}
let key = validated_metric_label_key(key)?;
let value = validated_metric_label_value(value)?;
if normalized.insert(key, value).is_some() {
return Err(MetricsError::DuplicateLabelKey);
}
}
normalized.retain(|_, value| !value.is_empty());
Ok(Self(normalized.into_iter().collect()))
}
#[must_use]
pub fn from_lossy(
labels: impl IntoIterator<Item = (impl Into<String>, impl Into<String>)>,
) -> Self {
let mut normalized = BTreeMap::<String, String>::new();
for (key, value) in labels.into_iter().take(MAX_METRIC_LABELS) {
if let (Ok(key), Ok(value)) = (
validated_metric_label_key(key),
validated_metric_label_value(value),
) {
normalized.insert(key, value);
}
}
normalized.retain(|_, value| !value.is_empty());
Self(normalized.into_iter().collect())
}
pub fn single(key: impl Into<String>, value: impl Into<String>) -> Result<Self, MetricsError> {
Self::new([(key, value)])
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.0.is_empty()
}
#[must_use]
pub fn as_slice(&self) -> &[(String, String)] {
&self.0
}
#[must_use]
pub fn get(&self, key: &str) -> Option<&str> {
self.0
.iter()
.find(|(name, _)| name == key)
.map(|(_, value)| value.as_str())
}
#[must_use]
pub fn to_btree_map(&self) -> BTreeMap<String, String> {
self.0.iter().cloned().collect()
}
#[must_use]
pub fn into_vec(self) -> Vec<(String, String)> {
self.0
}
}
impl<'de> Deserialize<'de> for MetricLabels {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
Self::new(Vec::<(String, String)>::deserialize(deserializer)?)
.map_err(serde::de::Error::custom)
}
}
#[derive(Clone, Default, PartialEq, Serialize)]
#[non_exhaustive]
pub struct MetricsSnapshot {
samples: Vec<MetricSample>,
}
impl fmt::Debug for MetricsSnapshot {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("MetricsSnapshot")
.field("sample_count", &self.samples.len())
.finish_non_exhaustive()
}
}
impl MetricsSnapshot {
pub fn new(samples: Vec<MetricSample>) -> Result<Self, MetricsError> {
let mut exported_names = BTreeMap::new();
let mut series = BTreeSet::new();
for sample in &samples {
let names = exported_metric_names(&sample.name, sample.kind);
validate_exported_names(&exported_names, &sample.name, sample.kind, &names)?;
if !series.insert((&sample.name, &sample.labels)) {
return Err(MetricsError::DuplicateSeries);
}
for name in names {
exported_names.insert(name, (sample.name.clone(), sample.kind));
}
}
Ok(Self { samples })
}
#[must_use]
pub fn samples(&self) -> &[MetricSample] {
&self.samples
}
}
impl<'de> Deserialize<'de> for MetricsSnapshot {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
#[derive(Deserialize)]
struct SnapshotWire {
samples: Vec<MetricSample>,
}
let wire = SnapshotWire::deserialize(deserializer)?;
Self::new(wire.samples).map_err(serde::de::Error::custom)
}
}
pub trait MetricRecorder: Send + Sync + 'static {
fn increment_counter(
&self,
name: &str,
value: u64,
labels: MetricLabels,
) -> Result<(), MetricsError>;
fn set_gauge(&self, name: &str, value: f64, labels: MetricLabels) -> Result<(), MetricsError>;
fn observe_histogram(
&self,
name: &str,
value: f64,
labels: MetricLabels,
) -> Result<(), MetricsError>;
fn snapshot(&self) -> Result<MetricsSnapshot, MetricsError>;
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub struct MetricRegistryLimits {
max_series: usize,
max_series_per_metric: usize,
max_label_value_length: usize,
}
impl MetricRegistryLimits {
pub const fn new(
max_series: usize,
max_series_per_metric: usize,
) -> Result<Self, MetricsError> {
if max_series == 0 || max_series_per_metric == 0 || max_series_per_metric > max_series {
return Err(MetricsError::InvalidRegistryLimits);
}
Ok(Self {
max_series,
max_series_per_metric,
max_label_value_length: DEFAULT_MAX_METRIC_LABEL_VALUE_LENGTH,
})
}
pub const fn with_max_label_value_length(mut self, max: usize) -> Result<Self, MetricsError> {
if max == 0 || max > MAX_METRIC_LABEL_VALUE_LENGTH {
return Err(MetricsError::InvalidRegistryLimits);
}
self.max_label_value_length = max;
Ok(self)
}
#[must_use]
pub const fn max_label_value_length(self) -> usize {
self.max_label_value_length
}
fn validate_labels(self, labels: &MetricLabels) -> Result<(), MetricsError> {
if labels
.as_slice()
.iter()
.any(|(_, value)| value.len() > self.max_label_value_length)
{
return Err(MetricsError::LabelValueTooLong {
max: self.max_label_value_length,
});
}
Ok(())
}
#[must_use]
pub const fn max_series(self) -> usize {
self.max_series
}
#[must_use]
pub const fn max_series_per_metric(self) -> usize {
self.max_series_per_metric
}
}
impl Default for MetricRegistryLimits {
fn default() -> Self {
Self {
max_series: DEFAULT_MAX_METRIC_SERIES,
max_series_per_metric: DEFAULT_MAX_METRIC_SERIES_PER_METRIC,
max_label_value_length: DEFAULT_MAX_METRIC_LABEL_VALUE_LENGTH,
}
}
}
#[derive(Default)]
#[non_exhaustive]
pub struct MetricRegistry {
state: Mutex<MetricRegistryState>,
limits: MetricRegistryLimits,
histogram_buckets: BTreeMap<String, Vec<f64>>,
}
impl fmt::Debug for MetricRegistry {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("MetricRegistry")
.field(
"metric_count",
&self.state.try_lock().ok().map(|state| state.values.len()),
)
.field("limits", &self.limits)
.finish_non_exhaustive()
}
}
impl MetricRegistry {
#[must_use]
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn with_limits(limits: MetricRegistryLimits) -> Self {
Self {
limits,
..Self::default()
}
}
pub fn with_histogram_buckets(
mut self,
name: &str,
bounds: Vec<f64>,
) -> Result<Self, MetricsError> {
validate_histogram_buckets(bounds.iter().copied())?;
let name = validated_metric_name(name, MetricKind::Histogram)?;
let state = self
.state
.get_mut()
.map_err(|_| MetricsError::LockPoisoned)?;
if state.series_per_metric.contains_key(&name) {
return Err(MetricsError::HistogramAlreadyObserved);
}
if !self.histogram_buckets.contains_key(&name)
&& self.histogram_buckets.len() >= self.limits.max_series
{
return Err(MetricsError::RegistrySeriesLimitExceeded {
max: self.limits.max_series,
});
}
self.histogram_buckets.insert(name, bounds);
Ok(self)
}
#[must_use]
pub const fn limits(&self) -> MetricRegistryLimits {
self.limits
}
pub fn remove_series(&self, name: &str, labels: MetricLabels) -> Result<bool, MetricsError> {
let name = validated_metric_name(name, MetricKind::Gauge)?;
let mut state = self.state.lock().map_err(|_| MetricsError::LockPoisoned)?;
let Some((owner, kind)) = state.exported_names.get(&name) else {
return Ok(false);
};
if owner != &name {
return Ok(false);
}
let identity = MetricIdentity::new(name, *kind, labels)?;
if state.values.remove(&identity).is_none() {
return Ok(false);
}
match state.series_per_metric.get_mut(&identity.name) {
Some(count) if *count > 1 => *count -= 1,
_ => {
state.series_per_metric.remove(&identity.name);
for name in exported_metric_names(&identity.name, identity.kind) {
state.exported_names.remove(&name);
}
}
}
Ok(true)
}
pub fn remove_family(&self, name: &str) -> Result<usize, MetricsError> {
let name = validated_metric_name(name, MetricKind::Gauge)?;
let mut state = self.state.lock().map_err(|_| MetricsError::LockPoisoned)?;
let removed = state.series_per_metric.remove(&name).unwrap_or_default();
if removed != 0 {
state.values.retain(|identity, _| identity.name != name);
state.exported_names.retain(|_, (owner, _)| owner != &name);
}
Ok(removed)
}
pub fn clear(&self) -> Result<(), MetricsError> {
*self.state.lock().map_err(|_| MetricsError::LockPoisoned)? =
MetricRegistryState::default();
Ok(())
}
pub fn replace_families<'a>(
&self,
names: impl IntoIterator<Item = &'a str>,
samples: impl IntoIterator<Item = MetricSample>,
) -> Result<(), MetricsError> {
let mut selected = BTreeSet::new();
for (index, name) in names.into_iter().enumerate() {
if index >= self.limits.max_series {
return Err(MetricsError::RegistrySeriesLimitExceeded {
max: self.limits.max_series,
});
}
selected.insert(validated_metric_name(name, MetricKind::Gauge)?);
}
let mut replacement = MetricRegistryState::default();
for sample in samples {
if !selected.contains(&sample.name) {
return Err(MetricsError::UnexpectedMetricFamily);
}
let identity =
MetricIdentity::new(sample.name, sample.kind, MetricLabels(sample.labels))?;
self.limits.validate_labels(&identity.labels)?;
if replacement.values.contains_key(&identity) {
return Err(MetricsError::DuplicateSeries);
}
if identity.kind == MetricKind::Histogram {
let bounds = self
.histogram_buckets
.get(&identity.name)
.map(Vec::as_slice)
.unwrap_or(DEFAULT_HISTOGRAM_BUCKETS);
if !sample
.buckets
.iter()
.map(|(bound, _)| bound)
.eq(bounds.iter())
{
return Err(MetricsError::HistogramBoundsMismatch);
}
}
replacement.insert_new(
identity,
MetricAggregate {
value: sample.value,
count: sample.count,
buckets: sample.buckets,
},
self.limits,
)?;
}
let mut state = self.state.lock().map_err(|_| MetricsError::LockPoisoned)?;
let removed: usize = selected
.iter()
.filter_map(|name| state.series_per_metric.get(name))
.sum();
if replacement.values.len() > self.limits.max_series - (state.values.len() - removed) {
return Err(MetricsError::RegistrySeriesLimitExceeded {
max: self.limits.max_series,
});
}
for name in replacement.exported_names.keys() {
if let Some((owner, _)) = state.exported_names.get(name)
&& !selected.contains(owner)
{
return Err(MetricsError::MetricNameConflict);
}
}
state
.values
.retain(|identity, _| !selected.contains(&identity.name));
state
.series_per_metric
.retain(|name, _| !selected.contains(name));
state
.exported_names
.retain(|_, (owner, _)| !selected.contains(owner));
state.values.append(&mut replacement.values);
state
.series_per_metric
.append(&mut replacement.series_per_metric);
state.exported_names.append(&mut replacement.exported_names);
Ok(())
}
pub fn increment_counter(
&self,
name: &str,
value: u64,
labels: MetricLabels,
) -> Result<(), MetricsError> {
MetricRecorder::increment_counter(self, name, value, labels)
}
pub fn set_gauge(
&self,
name: &str,
value: f64,
labels: MetricLabels,
) -> Result<(), MetricsError> {
MetricRecorder::set_gauge(self, name, value, labels)
}
pub fn observe_histogram(
&self,
name: &str,
value: f64,
labels: MetricLabels,
) -> Result<(), MetricsError> {
MetricRecorder::observe_histogram(self, name, value, labels)
}
pub fn snapshot(&self) -> Result<MetricsSnapshot, MetricsError> {
MetricRecorder::snapshot(self)
}
}
impl MetricRecorder for MetricRegistry {
fn increment_counter(
&self,
name: &str,
value: u64,
labels: MetricLabels,
) -> Result<(), MetricsError> {
let identity = MetricIdentity::new(name, MetricKind::Counter, labels)?;
self.limits.validate_labels(&identity.labels)?;
let mut state = self.state.lock().map_err(|_| MetricsError::LockPoisoned)?;
if let Some(aggregate) = state.values.get_mut(&identity) {
aggregate.value = finite_metric_sum(aggregate.value, value as f64)?;
} else {
state.insert_new(
identity,
MetricAggregate {
value: value as f64,
count: None,
buckets: Vec::new(),
},
self.limits,
)?;
}
Ok(())
}
fn set_gauge(&self, name: &str, value: f64, labels: MetricLabels) -> Result<(), MetricsError> {
validate_metric_value(value)?;
let identity = MetricIdentity::new(name, MetricKind::Gauge, labels)?;
self.limits.validate_labels(&identity.labels)?;
let mut state = self.state.lock().map_err(|_| MetricsError::LockPoisoned)?;
if let Some(aggregate) = state.values.get_mut(&identity) {
aggregate.value = value;
} else {
state.insert_new(
identity,
MetricAggregate {
value,
count: None,
buckets: Vec::new(),
},
self.limits,
)?;
}
Ok(())
}
fn observe_histogram(
&self,
name: &str,
value: f64,
labels: MetricLabels,
) -> Result<(), MetricsError> {
validate_metric_kind_value(MetricKind::Histogram, value)?;
let identity = MetricIdentity::new(name, MetricKind::Histogram, labels)?;
self.limits.validate_labels(&identity.labels)?;
let mut state = self.state.lock().map_err(|_| MetricsError::LockPoisoned)?;
if let Some(aggregate) = state.values.get_mut(&identity) {
let sum = finite_metric_sum(aggregate.value, value)?;
let count = aggregate
.count
.unwrap_or_default()
.checked_add(1)
.ok_or(MetricsError::CountOverflow)?;
aggregate.value = sum;
aggregate.count = Some(count);
for (bound, bucket_count) in &mut aggregate.buckets {
if value <= *bound {
*bucket_count += 1;
}
}
} else {
let buckets = self
.histogram_buckets
.get(&identity.name)
.map(Vec::as_slice)
.unwrap_or(DEFAULT_HISTOGRAM_BUCKETS)
.iter()
.map(|bound| (*bound, u64::from(value <= *bound)))
.collect();
state.insert_new(
identity,
MetricAggregate {
value,
count: Some(1),
buckets,
},
self.limits,
)?;
}
Ok(())
}
fn snapshot(&self) -> Result<MetricsSnapshot, MetricsError> {
let state = self.state.lock().map_err(|_| MetricsError::LockPoisoned)?;
let samples = state
.values
.iter()
.map(|(identity, aggregate)| MetricSample {
name: identity.name.clone(),
kind: identity.kind,
value: aggregate.value,
count: aggregate.count,
buckets: aggregate.buckets.clone(),
labels: identity.labels.clone().into_vec(),
})
.collect();
Ok(MetricsSnapshot { samples })
}
}
fn finite_metric_sum(left: f64, right: f64) -> Result<f64, MetricsError> {
let sum = left + right;
validate_metric_value(sum)?;
Ok(sum)
}
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
struct MetricIdentity {
name: String,
kind: MetricKind,
labels: MetricLabels,
}
impl MetricIdentity {
fn new(
name: impl Into<String>,
kind: MetricKind,
labels: MetricLabels,
) -> Result<Self, MetricsError> {
validate_metric_kind_labels(kind, &labels)?;
Ok(Self {
name: validated_metric_name(name, kind)?,
kind,
labels,
})
}
}
#[derive(Debug, Clone, PartialEq)]
struct MetricAggregate {
value: f64,
count: Option<u64>,
buckets: Vec<(f64, u64)>,
}
#[derive(Default)]
struct MetricRegistryState {
values: BTreeMap<MetricIdentity, MetricAggregate>,
series_per_metric: BTreeMap<String, usize>,
exported_names: BTreeMap<String, (String, MetricKind)>,
}
impl MetricRegistryState {
fn insert_new(
&mut self,
identity: MetricIdentity,
aggregate: MetricAggregate,
limits: MetricRegistryLimits,
) -> Result<(), MetricsError> {
let names = exported_metric_names(&identity.name, identity.kind);
validate_exported_names(&self.exported_names, &identity.name, identity.kind, &names)?;
if self.values.len() >= limits.max_series {
return Err(MetricsError::RegistrySeriesLimitExceeded {
max: limits.max_series,
});
}
let metric_series = self
.series_per_metric
.get(&identity.name)
.copied()
.unwrap_or_default();
if metric_series >= limits.max_series_per_metric {
return Err(MetricsError::MetricSeriesLimitExceeded {
max: limits.max_series_per_metric,
});
}
let metric_name = identity.name.clone();
for name in names {
self.exported_names
.insert(name, (metric_name.clone(), identity.kind));
}
self.values.insert(identity, aggregate);
self.series_per_metric
.insert(metric_name, metric_series.saturating_add(1));
Ok(())
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]
#[non_exhaustive]
pub enum MetricsError {
#[error("sample does not belong to a selected metric family")]
UnexpectedMetricFamily,
#[error("duplicate metric series")]
DuplicateSeries,
#[error("duplicate metric label key")]
DuplicateLabelKey,
#[error("histogram bounds do not match the registry configuration")]
HistogramBoundsMismatch,
#[error(
"histogram bounds must be nonempty, finite, nonnegative, strictly increasing, and within the bucket limit"
)]
InvalidHistogramBuckets,
#[error("histogram count, sum, or cumulative bucket counts are inconsistent")]
InvalidHistogram,
#[error("histogram bounds cannot change after observations")]
HistogramAlreadyObserved,
#[error("histogram observation count overflowed")]
CountOverflow,
#[error("histogram labels must not contain the reserved 'le' label")]
ReservedHistogramLabel,
#[error("counter and histogram values must not be negative")]
NegativeValue,
#[error("metric name is already registered with a different type")]
MetricTypeConflict,
#[error("metric name conflicts with another exported metric family or sample")]
MetricNameConflict,
#[error("metrics registry lock is poisoned")]
LockPoisoned,
#[error(
"metric name must start with an ASCII letter or ':' and contain only ASCII letters, digits, '_' or ':'"
)]
InvalidName,
#[error("metric name must be less than or equal to {max} bytes")]
NameTooLong {
#[doc = "The configured upper bound."]
max: usize,
},
#[error("metric must contain at most {max} labels")]
TooManyLabels {
#[doc = "The configured upper bound."]
max: usize,
},
#[error(
"metric label key must start with an ASCII letter or '_', contain only ASCII letters, digits or '_', and must not start with '__'"
)]
InvalidLabelKey,
#[error("metric label key must be less than or equal to {max} bytes")]
LabelKeyTooLong {
#[doc = "The configured upper bound."]
max: usize,
},
#[error("metric label value must not contain control characters")]
InvalidLabelValue,
#[error("metric label value must be less than or equal to {max} bytes")]
LabelValueTooLong {
#[doc = "The configured upper bound."]
max: usize,
},
#[error("metric value must be finite")]
InvalidValue,
#[error(
"registry limits must be non-zero, the per-metric limit must not exceed the total, and label values must fit the hard input bound"
)]
InvalidRegistryLimits,
#[error("metric registry series limit of {max} was exceeded")]
RegistrySeriesLimitExceeded {
#[doc = "The configured upper bound."]
max: usize,
},
#[error("per-metric series limit of {max} was exceeded")]
MetricSeriesLimitExceeded {
#[doc = "The configured upper bound."]
max: usize,
},
}
impl ClassifyError for MetricsError {
fn error_kind(&self) -> ErrorKind {
match self {
Self::LockPoisoned => ErrorKind::Unavailable,
Self::InvalidHistogramBuckets
| Self::UnexpectedMetricFamily
| Self::DuplicateSeries
| Self::DuplicateLabelKey
| Self::HistogramBoundsMismatch
| Self::InvalidHistogram
| Self::HistogramAlreadyObserved
| Self::CountOverflow
| Self::InvalidName
| Self::ReservedHistogramLabel
| Self::NegativeValue
| Self::MetricTypeConflict
| Self::MetricNameConflict
| Self::NameTooLong { .. }
| Self::TooManyLabels { .. }
| Self::InvalidLabelKey
| Self::LabelKeyTooLong { .. }
| Self::InvalidLabelValue
| Self::LabelValueTooLong { .. }
| Self::InvalidValue
| Self::InvalidRegistryLimits
| Self::RegistrySeriesLimitExceeded { .. }
| Self::MetricSeriesLimitExceeded { .. } => ErrorKind::Validation,
}
}
fn error_code(&self) -> crate::result::ErrorCode {
crate::result::ErrorCode::internal(match self {
Self::UnexpectedMetricFamily => "metric_family_unexpected",
Self::DuplicateSeries => "metric_series_duplicate",
Self::DuplicateLabelKey => "metric_label_key_duplicate",
Self::HistogramBoundsMismatch => "metric_histogram_bounds_mismatch",
Self::InvalidHistogramBuckets => "metric_histogram_buckets_invalid",
Self::InvalidHistogram => "metric_histogram_invalid",
Self::HistogramAlreadyObserved => "metric_histogram_already_observed",
Self::CountOverflow => "metric_count_overflow",
Self::ReservedHistogramLabel => "metric_histogram_label_reserved",
Self::NegativeValue => "metric_value_negative",
Self::MetricTypeConflict => "metric_type_conflict",
Self::MetricNameConflict => "metric_name_conflict",
Self::LockPoisoned => "metrics_registry_unavailable",
Self::InvalidName => "metric_name_invalid",
Self::NameTooLong { .. } => "metric_name_too_long",
Self::TooManyLabels { .. } => "metric_labels_too_many",
Self::InvalidLabelKey => "metric_label_key_invalid",
Self::LabelKeyTooLong { .. } => "metric_label_key_too_long",
Self::InvalidLabelValue => "metric_label_value_invalid",
Self::LabelValueTooLong { .. } => "metric_label_value_too_long",
Self::InvalidValue => "metric_value_invalid",
Self::InvalidRegistryLimits => "metrics_registry_limits_invalid",
Self::RegistrySeriesLimitExceeded { .. } => "metrics_registry_series_limit_exceeded",
Self::MetricSeriesLimitExceeded { .. } => "metric_series_limit_exceeded",
})
}
}
fn validate_histogram_buckets(bounds: impl Iterator<Item = f64>) -> Result<(), MetricsError> {
let mut previous = None;
let mut count = 0;
for bound in bounds {
count += 1;
if count > MAX_HISTOGRAM_BUCKETS
|| !bound.is_finite()
|| bound < 0.0
|| previous.is_some_and(|last| bound <= last)
{
return Err(MetricsError::InvalidHistogramBuckets);
}
previous = Some(bound);
}
if count == 0 {
return Err(MetricsError::InvalidHistogramBuckets);
}
Ok(())
}
fn validate_metric_kind_value(kind: MetricKind, value: f64) -> Result<(), MetricsError> {
validate_metric_value(value)?;
if kind != MetricKind::Gauge && value < 0.0 {
return Err(MetricsError::NegativeValue);
}
Ok(())
}
fn validate_metric_kind_labels(
kind: MetricKind,
labels: &MetricLabels,
) -> Result<(), MetricsError> {
if kind == MetricKind::Histogram && labels.get("le").is_some() {
return Err(MetricsError::ReservedHistogramLabel);
}
Ok(())
}
fn metric_family_name(name: &str, kind: MetricKind) -> &str {
if kind == MetricKind::Counter {
name.strip_suffix("_total").unwrap_or(name)
} else {
name
}
}
fn exported_metric_names(name: &str, kind: MetricKind) -> Vec<String> {
let family = metric_family_name(name, kind);
let suffixes: &[&str] = match kind {
MetricKind::Counter => &["", "_total", "_created"],
MetricKind::Gauge => &[""],
MetricKind::Histogram => &["", "_sum", "_count", "_bucket", "_created"],
};
suffixes
.iter()
.map(|suffix| format!("{family}{suffix}"))
.collect()
}
fn validate_exported_names(
registered: &BTreeMap<String, (String, MetricKind)>,
owner: &str,
kind: MetricKind,
names: &[String],
) -> Result<(), MetricsError> {
for name in names {
if let Some((existing_owner, existing_kind)) = registered.get(name) {
if existing_owner != owner {
return Err(MetricsError::MetricNameConflict);
}
if *existing_kind != kind {
return Err(MetricsError::MetricTypeConflict);
}
}
}
Ok(())
}
#[must_use]
pub fn encode_openmetrics(snapshot: &MetricsSnapshot) -> String {
encode_metrics(snapshot, true)
}
#[must_use]
pub fn encode_prometheus(snapshot: &MetricsSnapshot) -> String {
encode_metrics(snapshot, false)
}
fn encode_metrics(snapshot: &MetricsSnapshot, openmetrics: bool) -> String {
let mut output = String::new();
let mut previous_family = None;
let mut samples: Vec<_> = snapshot.samples().iter().collect();
samples.sort_by_key(|sample| metric_family_name(sample.name(), sample.kind()));
for sample in samples {
let name = sample.name();
let family = metric_family_name(name, sample.kind());
if previous_family != Some(family) {
let suffix = if !openmetrics && sample.kind() == MetricKind::Counter {
"_total"
} else {
""
};
let _ = writeln!(
output,
"# TYPE {family}{suffix} {}",
openmetrics_kind(sample.kind())
);
previous_family = Some(family);
}
let labels = sample.labels();
let value = sample.value();
match (sample.kind(), sample.count()) {
(MetricKind::Histogram, Some(count)) => {
for (bound, bucket_count) in sample.buckets() {
write_sample(
&mut output,
name,
"_bucket",
labels,
bucket_count,
Some(*bound),
);
}
write_sample(
&mut output,
name,
"_bucket",
labels,
count,
Some(f64::INFINITY),
);
write_sample(&mut output, name, "_sum", labels, value, None);
write_sample(&mut output, name, "_count", labels, count, None);
}
_ => {
let suffix = if sample.kind() == MetricKind::Counter {
"_total"
} else {
""
};
write_sample(&mut output, family, suffix, labels, value, None);
}
}
}
if openmetrics {
output.push_str("# EOF\n");
}
output
}
fn validated_metric_name(
value: impl Into<String>,
kind: MetricKind,
) -> Result<String, MetricsError> {
let value = value.into();
if value.len() > MAX_METRIC_NAME_LENGTH {
return Err(MetricsError::NameTooLong {
max: MAX_METRIC_NAME_LENGTH,
});
}
if !value
.as_bytes()
.first()
.is_some_and(|byte| byte.is_ascii_alphabetic() || *byte == b':')
|| !value
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b':' | b'_'))
|| metric_family_name(&value, kind).is_empty()
{
return Err(MetricsError::InvalidName);
}
Ok(value)
}
fn validated_metric_label_key(value: impl Into<String>) -> Result<String, MetricsError> {
let value = value.into();
if value.len() > MAX_METRIC_LABEL_KEY_LENGTH {
return Err(MetricsError::LabelKeyTooLong {
max: MAX_METRIC_LABEL_KEY_LENGTH,
});
}
if !value
.as_bytes()
.first()
.is_some_and(|byte| byte.is_ascii_alphabetic() || *byte == b'_')
|| !value
.bytes()
.all(|byte| byte.is_ascii_alphanumeric() || byte == b'_')
|| value.starts_with("__")
{
return Err(MetricsError::InvalidLabelKey);
}
Ok(value)
}
fn validated_metric_label_value(value: impl Into<String>) -> Result<String, MetricsError> {
let value = value.into();
if value.len() > MAX_METRIC_LABEL_VALUE_LENGTH {
return Err(MetricsError::LabelValueTooLong {
max: MAX_METRIC_LABEL_VALUE_LENGTH,
});
}
if value.chars().any(char::is_control) {
return Err(MetricsError::InvalidLabelValue);
}
Ok(value)
}
fn validate_metric_value(value: f64) -> Result<(), MetricsError> {
if value.is_finite() {
Ok(())
} else {
Err(MetricsError::InvalidValue)
}
}
fn openmetrics_kind(kind: MetricKind) -> &'static str {
match kind {
MetricKind::Counter => "counter",
MetricKind::Gauge => "gauge",
MetricKind::Histogram => "histogram",
}
}
fn write_sample(
output: &mut String,
name: &str,
suffix: &str,
labels: &[(String, String)],
value: impl fmt::Display,
bound: Option<f64>,
) {
output.push_str(name);
output.push_str(suffix);
write_labels(output, labels, bound);
let _ = writeln!(output, " {value}");
}
fn write_labels(output: &mut String, labels: &[(String, String)], bound: Option<f64>) {
if labels.is_empty() && bound.is_none() {
return;
}
output.push('{');
for (index, (key, value)) in labels.iter().enumerate() {
if index > 0 {
output.push(',');
}
output.push_str(key);
output.push_str("=\"");
for character in value.chars() {
match character {
'\\' => output.push_str("\\\\"),
'"' => output.push_str("\\\""),
'\n' => output.push_str("\\n"),
_ => output.push(character),
}
}
output.push('"');
}
if let Some(bound) = bound {
if !labels.is_empty() {
output.push(',');
}
if bound == f64::INFINITY {
output.push_str("le=\"+Inf\"");
} else {
let _ = write!(output, "le=\"{bound}\"");
}
}
output.push('}');
}
#[cfg(test)]
mod tests {
use super::*;
fn gauge(name: &str, resource: &str, value: f64) -> MetricSample {
MetricSample::gauge(name, value)
.unwrap()
.with_label("resource", resource)
.unwrap()
}
#[test]
fn replacement_reuses_capacity_and_rolls_back_all_validation_failures() {
let registry = MetricRegistry::with_limits(MetricRegistryLimits::new(3, 2).unwrap());
registry
.increment_counter("requests_total", 9, MetricLabels::default())
.unwrap();
registry
.replace_families(
["cpu", "memory"],
[gauge("cpu", "old", 1.0), gauge("memory", "old", 2.0)],
)
.unwrap();
registry
.replace_families(
["cpu", "memory"],
[gauge("cpu", "new", 3.0), gauge("memory", "new", 4.0)],
)
.unwrap();
let before = registry.snapshot().unwrap();
assert!(
before
.samples()
.iter()
.flat_map(|s| s.labels())
.all(|(_, value)| value != "old")
);
assert_eq!(
before
.samples()
.iter()
.find(|s| s.name() == "requests_total")
.unwrap()
.value(),
9.0
);
for (selected, samples, error) in [
(
vec!["cpu"],
vec![gauge("memory", "new", 0.0)],
MetricsError::UnexpectedMetricFamily,
),
(
vec!["cpu"],
vec![gauge("cpu", "new", 0.0), gauge("cpu", "new", 1.0)],
MetricsError::DuplicateSeries,
),
(
vec!["cpu"],
vec![gauge("cpu", "one", 0.0), gauge("cpu", "two", 1.0)],
MetricsError::RegistrySeriesLimitExceeded { max: 3 },
),
(
vec!["cpu"],
vec![
gauge("cpu", "one", 0.0),
gauge("cpu", "two", 1.0),
gauge("cpu", "three", 2.0),
],
MetricsError::MetricSeriesLimitExceeded { max: 2 },
),
(
vec!["cpu", "requests"],
vec![gauge("requests", "new", 1.0)],
MetricsError::MetricNameConflict,
),
(
vec!["cpu"],
vec![gauge("cpu", &"x".repeat(257), 1.0)],
MetricsError::LabelValueTooLong { max: 256 },
),
] {
assert_eq!(registry.replace_families(selected, samples), Err(error));
assert_eq!(registry.snapshot().unwrap(), before);
}
registry.replace_families(["cpu", "memory"], []).unwrap();
assert_eq!(registry.snapshot().unwrap().samples().len(), 1);
}
#[test]
fn removals_release_names_and_capacity_but_keep_histogram_configuration() {
let registry = MetricRegistry::with_limits(MetricRegistryLimits::new(2, 2).unwrap())
.with_histogram_buckets("latency", vec![1.0, 3.0])
.unwrap();
let labels = MetricLabels::single("resource", "a").unwrap();
registry
.observe_histogram("latency", 2.0, labels.clone())
.unwrap();
registry
.observe_histogram("latency", 2.0, MetricLabels::default())
.unwrap();
assert!(registry.remove_series("latency", labels.clone()).unwrap());
assert!(!registry.remove_series("latency", labels).unwrap());
assert_eq!(
registry.set_gauge("latency_sum", 0.0, MetricLabels::default()),
Err(MetricsError::MetricNameConflict)
);
assert_eq!(registry.remove_family("latency_sum").unwrap(), 0);
assert!(
registry
.remove_series("latency", MetricLabels::default())
.unwrap()
);
registry
.set_gauge("latency_sum", 0.0, MetricLabels::default())
.unwrap();
assert_eq!(registry.remove_family("latency_sum").unwrap(), 1);
registry
.increment_counter("jobs_total", 1, MetricLabels::default())
.unwrap();
assert!(
!registry
.remove_series("jobs", MetricLabels::default())
.unwrap()
);
assert!(
registry
.remove_series("jobs_total", MetricLabels::default())
.unwrap()
);
registry
.set_gauge("jobs", 1.0, MetricLabels::default())
.unwrap();
registry.clear().unwrap();
registry
.observe_histogram("latency", 2.0, MetricLabels::default())
.unwrap();
assert_eq!(
registry.snapshot().unwrap().samples()[0].buckets(),
&[(1.0, 0), (3.0, 1)]
);
}
#[test]
fn replacement_histograms_remain_compatible_with_future_observations() {
let registry = MetricRegistry::new()
.with_histogram_buckets("latency", vec![1.0, 3.0])
.unwrap();
let sample = MetricSample::histogram("latency", 1, 2.0, vec![(1.0, 0), (3.0, 1)]).unwrap();
registry.replace_families(["latency"], [sample]).unwrap();
let before = registry.snapshot().unwrap();
let mismatch = MetricSample::histogram("latency", 1, 2.0, vec![(4.0, 1)]).unwrap();
assert_eq!(
registry.replace_families(["latency"], [mismatch]),
Err(MetricsError::HistogramBoundsMismatch)
);
assert_eq!(registry.snapshot().unwrap(), before);
registry
.observe_histogram("latency", 0.5, MetricLabels::default())
.unwrap();
let snapshot = registry.snapshot().unwrap();
assert_eq!(snapshot.samples()[0].buckets(), &[(1.0, 1), (3.0, 2)]);
assert_eq!(snapshot.samples()[0].value(), 2.5);
}
#[test]
fn configurable_label_limits_apply_to_all_writes_and_round_trip_long_values() {
let limits = MetricRegistryLimits::default()
.with_max_label_value_length(1024)
.unwrap();
assert_eq!(limits.max_label_value_length(), 1024);
assert!(limits.with_max_label_value_length(0).is_err());
assert!(
limits
.with_max_label_value_length(MAX_METRIC_LABEL_VALUE_LENGTH + 1)
.is_err()
);
let registry = MetricRegistry::with_limits(limits);
let value = "镜".repeat(200); let labels = MetricLabels::single("image", &value).unwrap();
assert_eq!(
MetricRegistry::new().set_gauge("image_info", 1.0, labels.clone()),
Err(MetricsError::LabelValueTooLong { max: 256 })
);
registry
.set_gauge("image_info", 1.0, labels.clone())
.unwrap();
registry
.increment_counter("pulls_total", 1, labels.clone())
.unwrap();
registry
.observe_histogram("pull_seconds", 0.5, labels)
.unwrap();
let snapshot = registry.snapshot().unwrap();
assert_eq!(
serde_json::from_str::<MetricsSnapshot>(&serde_json::to_string(&snapshot).unwrap())
.unwrap(),
snapshot
);
assert!(encode_openmetrics(&snapshot).contains(&value));
let too_long = MetricLabels::single("image", "x".repeat(1025)).unwrap();
assert!(
registry
.set_gauge("image_info", 1.0, too_long.clone())
.is_err()
);
assert!(
registry
.increment_counter("pulls_total", 1, too_long.clone())
.is_err()
);
assert!(
registry
.observe_histogram("pull_seconds", 0.5, too_long)
.is_err()
);
assert_eq!(registry.snapshot().unwrap(), snapshot);
}
#[test]
fn concurrent_scrapes_never_observe_half_a_replacement() {
let registry = MetricRegistry::new();
let barrier = std::sync::Barrier::new(3);
registry
.increment_counter("requests_total", 0, MetricLabels::default())
.unwrap();
registry
.replace_families(
["cpu", "memory"],
[gauge("cpu", "a", 0.0), gauge("memory", "a", 0.0)],
)
.unwrap();
std::thread::scope(|scope| {
scope.spawn(|| {
barrier.wait();
for _ in 0..200 {
registry
.increment_counter("requests_total", 1, MetricLabels::default())
.unwrap();
std::thread::yield_now();
}
});
scope.spawn(|| {
barrier.wait();
for value in 1..200 {
registry
.replace_families(
["cpu", "memory"],
[
gauge("cpu", "a", f64::from(value)),
gauge("memory", "a", f64::from(value)),
],
)
.unwrap();
std::thread::yield_now();
}
});
barrier.wait();
for _ in 0..200 {
let snapshot = registry.snapshot().unwrap();
assert_eq!(snapshot.samples().len(), 3);
assert_eq!(snapshot.samples()[0].value(), snapshot.samples()[1].value());
std::thread::yield_now();
}
});
assert_eq!(registry.snapshot().unwrap().samples()[2].value(), 200.0);
}
#[test]
fn histogram_count_overflow_leaves_sum_and_buckets_unchanged() {
let registry = MetricRegistry::new();
registry
.observe_histogram("latency", 0.0, MetricLabels::default())
.unwrap();
{
let mut state = registry.state.lock().unwrap();
let aggregate = state.values.values_mut().next().unwrap();
aggregate.count = Some(u64::MAX);
aggregate
.buckets
.iter_mut()
.for_each(|(_, count)| *count = u64::MAX);
}
let before = registry.snapshot().unwrap();
assert_eq!(
registry.observe_histogram("latency", 1.0, MetricLabels::default()),
Err(MetricsError::CountOverflow)
);
assert_eq!(registry.snapshot().unwrap(), before);
}
}