use std::{
collections::BTreeMap,
convert::Infallible,
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 = 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 = normalize_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 = normalize_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(
normalize_metric_name(name, MetricKind::Histogram)?,
MetricKind::Histogram,
sum,
);
sample.count = Some(count);
sample.buckets = buckets;
Ok(sample)
}
#[must_use]
pub fn with_label(mut self, key: &'static str, value: impl Into<String>) -> Self {
let _ = self.insert_label(key.to_owned(), value.into());
self
}
pub fn try_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 = normalize_metric_label_key(key)?;
let value = normalize_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) => self.labels[index].1 = value,
Err(index) => {
if self.labels.len() >= MAX_METRIC_LABELS {
return Err(MetricsError::TooManyLabels {
max: MAX_METRIC_LABELS,
});
}
self.labels.insert(index, (key, value));
}
}
Ok(())
}
#[must_use]
pub fn with_labels(mut self, labels: MetricLabels) -> Self {
self.labels = labels.into_vec();
if self.kind == MetricKind::Histogram {
self.labels.retain(|(key, _)| key != "le");
}
self
}
pub fn try_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
.try_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 = normalize_metric_label_key(key)?;
let value = normalize_metric_label_value(value)?;
normalized.insert(key, value);
}
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)) = (
normalize_metric_label_key(key),
normalize_metric_label_value(value),
) {
normalized.insert(key, value);
}
}
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> {
let key = normalize_metric_label_key(key).ok()?;
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, Deserialize)]
#[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 {
#[must_use]
pub fn new(samples: Vec<MetricSample>) -> Self {
Self { samples }
}
pub fn push(&mut self, sample: MetricSample) {
self.samples.push(sample);
}
#[must_use]
pub fn samples(&self) -> &[MetricSample] {
&self.samples
}
}
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,
}
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,
})
}
#[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,
}
}
}
#[non_exhaustive]
pub struct MetricRegistry {
state: Mutex<MetricRegistryState>,
limits: MetricRegistryLimits,
histogram_buckets: BTreeMap<String, Vec<f64>>,
}
impl Default for MetricRegistry {
fn default() -> Self {
Self {
state: Mutex::new(MetricRegistryState::default()),
limits: MetricRegistryLimits::default(),
histogram_buckets: BTreeMap::new(),
}
}
}
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 {
state: Mutex::new(MetricRegistryState::default()),
limits,
histogram_buckets: BTreeMap::new(),
}
}
pub fn with_histogram_buckets(
mut self,
name: &str,
bounds: Vec<f64>,
) -> Result<Self, MetricsError> {
validate_histogram_buckets(bounds.iter().copied())?;
let name = normalize_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 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)?;
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)?;
let mut state = self.state.lock().map_err(|_| MetricsError::LockPoisoned)?;
if let Some(aggregate) = state.values.get_mut(&identity) {
*aggregate = MetricAggregate {
value,
count: None,
buckets: Vec::new(),
};
} 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)?;
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::new(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: normalize_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);
for name in &names {
if let Some((owner, kind)) = self.exported_names.get(name) {
if owner == &identity.name && *kind != identity.kind {
return Err(MetricsError::MetricTypeConflict);
}
if owner != &identity.name {
return Err(MetricsError::MetricNameConflict);
}
}
}
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(
"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 not be empty")]
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 not be empty")]
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(
"metric registry limits must be non-zero and the per-metric limit must not exceed the total limit"
)]
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::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::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()
}
#[must_use]
pub fn encode_openmetrics(snapshot: &MetricsSnapshot) -> 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 _ = writeln!(
output,
"# TYPE {family} {}",
openmetrics_kind(sample.kind())
);
previous_family = Some(family);
}
let labels = sample.labels();
let value = if sample.value().is_finite() {
sample.value()
} else {
0.0
};
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);
}
}
}
output.push_str("# EOF\n");
output
}
#[derive(Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct MetricsExport {
content_type: String,
body: String,
}
impl fmt::Debug for MetricsExport {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("MetricsExport")
.field("content_type", &self.content_type)
.field("body_bytes", &self.body.len())
.finish()
}
}
impl MetricsExport {
#[must_use]
pub fn new(content_type: impl Into<String>, body: impl Into<String>) -> Self {
Self {
content_type: content_type.into(),
body: body.into(),
}
}
#[must_use]
pub fn content_type(&self) -> &str {
&self.content_type
}
#[must_use]
pub fn body(&self) -> &str {
&self.body
}
#[must_use]
pub fn into_body(self) -> String {
self.body
}
}
pub trait MetricsExporter {
type Error;
fn export(&self, snapshot: &MetricsSnapshot) -> Result<MetricsExport, Self::Error>;
}
#[derive(Debug, Clone, Copy, Default)]
#[non_exhaustive]
pub struct OpenMetricsExporter;
impl OpenMetricsExporter {
pub const CONTENT_TYPE: &'static str =
"application/openmetrics-text; version=1.0.0; charset=utf-8";
}
impl MetricsExporter for OpenMetricsExporter {
type Error = Infallible;
fn export(&self, snapshot: &MetricsSnapshot) -> Result<MetricsExport, Self::Error> {
Ok(MetricsExport::new(
Self::CONTENT_TYPE,
encode_openmetrics(snapshot),
))
}
}
fn normalize_metric_name(
value: impl Into<String>,
kind: MetricKind,
) -> Result<String, MetricsError> {
let value = value.into();
let value = value.trim();
if value.is_empty() {
return Err(MetricsError::InvalidName);
}
if value.len() > MAX_METRIC_NAME_LENGTH {
return Err(MetricsError::NameTooLong {
max: MAX_METRIC_NAME_LENGTH,
});
}
let mut normalized = String::with_capacity(value.len().max(1));
for byte in value.bytes() {
if byte.is_ascii_alphanumeric() || byte == b':' || byte == b'_' {
normalized.push(char::from(byte));
} else {
normalized.push('_');
}
}
if normalized.as_bytes().first().is_none_or(u8::is_ascii_digit) {
normalized.insert(0, '_');
}
if normalized.len() > MAX_METRIC_NAME_LENGTH {
return Err(MetricsError::NameTooLong {
max: MAX_METRIC_NAME_LENGTH,
});
}
if metric_family_name(&normalized, kind).is_empty() {
return Err(MetricsError::InvalidName);
}
Ok(normalized)
}
fn normalize_metric_label_key(value: impl Into<String>) -> Result<String, MetricsError> {
let value = value.into();
let value = value.trim();
if value.is_empty() {
return Err(MetricsError::InvalidLabelKey);
}
if value.len() > MAX_METRIC_LABEL_KEY_LENGTH {
return Err(MetricsError::LabelKeyTooLong {
max: MAX_METRIC_LABEL_KEY_LENGTH,
});
}
let mut normalized = String::with_capacity(value.len().max(1));
for byte in value.bytes() {
if byte.is_ascii_alphanumeric() || byte == b'_' {
normalized.push(char::from(byte));
} else {
normalized.push('_');
}
}
if normalized.as_bytes().first().is_none_or(u8::is_ascii_digit) {
normalized.insert(0, '_');
}
if normalized.len() > MAX_METRIC_LABEL_KEY_LENGTH {
return Err(MetricsError::LabelKeyTooLong {
max: MAX_METRIC_LABEL_KEY_LENGTH,
});
}
Ok(normalized)
}
fn normalize_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::*;
#[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);
}
}