Struct Family

Source

pub struct Family<S, M, C = fn() -> M> { /* private fields */ }

Expand description

Representation of the OpenMetrics MetricFamily data type.

A Family is a set of metrics with the same name, help text and type, differentiated by their label values thus spanning a multidimensional space.

§Generic over the label set

A Family is generic over the label type. For convenience one might choose a Vec<(String, String)>, for performance and/or type safety one might define a custom type.

§Examples

§`Family` with `Vec<(String, String)>` for convenience

let family = Family::<Vec<(String, String)>, Counter>::default();

// Record a single HTTP GET request.
family.get_or_create(&vec![("method".to_owned(), "GET".to_owned())]).inc();

§`Family` with custom type for performance and/or type safety

Using EncodeLabelSet and EncodeLabelValue derive macro to generate EncodeLabelSet for structs and EncodeLabelValue for enums.

#[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelSet)]
struct Labels {
  method: Method,
};

#[derive(Clone, Debug, Hash, PartialEq, Eq, EncodeLabelValue)]
enum Method {
  GET,
  PUT,
};

let family = Family::<Labels, Counter>::default();

// Record a single HTTP GET request.
family.get_or_create(&Labels { method: Method::GET }).inc();

Implementations§

Source §

impl<S: Clone + Hash + Eq, M, C> Family<S, M, C>

Source

pub fn new_with_constructor(constructor: C) -> Self

Create a metric family using a custom constructor to construct new metrics.

When calling Family::get_or_create a Family needs to be able to construct a new metric in case none exists for the given label set. In most cases, e.g. for Counter Family can just use the Default::default implementation for the metric type. For metric types such as Histogram one might want Family to construct a Histogram with custom buckets (see example below). For such case one can use this method. For more involved constructors see MetricConstructor.

Family::<Vec<(String, String)>, Histogram>::new_with_constructor(|| {
    Histogram::new(exponential_buckets(1.0, 2.0, 10))
});

Source §

impl<S: Clone + Hash + Eq, M, C: MetricConstructor<M>> Family<S, M, C>

Source

pub fn get_or_create(&self, label_set: &S) -> MappedRwLockReadGuard<'_, M>

Access a metric with the given label set, creating it if one does not yet exist.

let family = Family::<Vec<(String, String)>, Counter>::default();

// Will create the metric with label `method="GET"` on first call and
// return a reference.
family.get_or_create(&vec![("method".to_owned(), "GET".to_owned())]).inc();

// Will return a reference to the existing metric on all subsequent
// calls.
family.get_or_create(&vec![("method".to_owned(), "GET".to_owned())]).inc();

Source

pub fn get(&self, label_set: &S) -> Option<MappedRwLockReadGuard<'_, M>>

Access a metric with the given label set, returning None if one does not yet exist.

let family = Family::<Vec<(String, String)>, Counter>::default();

if let Some(metric) = family.get(&vec![("method".to_owned(), "GET".to_owned())]) {
    metric.inc();
};

Source

pub fn remove(&self, label_set: &S) -> bool

Remove a label set from the metric family.

Returns a bool indicating if a label set was removed or not.

let family = Family::<Vec<(String, String)>, Counter>::default();

// Will create the metric with label `method="GET"` on first call and
// return a reference.
family.get_or_create(&vec![("method".to_owned(), "GET".to_owned())]).inc();

// Will return `true`, indicating that the `method="GET"` label set was
// removed.
assert!(family.remove(&vec![("method".to_owned(), "GET".to_owned())]));

Source

pub fn clear(&self)

Clear all label sets from the metric family.

let family = Family::<Vec<(String, String)>, Counter>::default();

// Will create the metric with label `method="GET"` on first call and
// return a reference.
family.get_or_create(&vec![("method".to_owned(), "GET".to_owned())]).inc();

// Clear the family of all label sets.
family.clear();