Struct Family 

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

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

impl<S, M, C> Family<S, M, C>

where S: Clone + Hash + Eq,

pub fn new_with_constructor(constructor: C) -> Family<S, M, C>

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))
});

impl<S, M, C> Family<S, M, C>

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

pub fn get_or_create_owned(&self, label_set: &S) -> 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 and return the metric with label `method="GET"` when first called.
family.get_or_create_owned(&vec![("method".to_owned(), "GET".to_owned())]).inc();

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

Callers wishing to avoid a clone of the metric M can call Family::get_or_create() to return a reference to the metric instead.

impl<S, M, C> Family<S, M, C>

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

pub fn get_or_create( &self, label_set: &S, ) -> MappedRwLockReadGuard<'_, RawRwLock, 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();

NB: This method can cause deadlocks if multiple metrics within this family are read at once. Use Family::get_or_create_owned() if you would like to avoid this by cloning the metric M.

pub fn get( &self, label_set: &S, ) -> Option<MappedRwLockReadGuard<'_, RawRwLock, 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();
};

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())]));

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();

Trait Implementations

impl<S, M, C> Clone for Family<S, M, C>

where C: Clone,

fn clone(&self) -> Family<S, M, C>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S, M, C> Debug for Family<S, M, C>

where S: Debug, M: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<S, M> Default for Family<S, M>

where S: Clone + Hash + Eq, M: Default,

fn default() -> Family<S, M>

Returns the “default value” for a type.

impl<S, M, C> EncodeMetric for Family<S, M, C>

where S: Clone + Hash + Eq + EncodeLabelSet, M: EncodeMetric + TypedMetric, C: MetricConstructor<M>,

fn encode(&self, encoder: MetricEncoder<'_>) -> Result<(), Error>

Encode the given instance in the OpenMetrics text encoding.

fn metric_type(&self) -> MetricType

The OpenMetrics metric type of the instance.

fn is_empty(&self) -> bool

Check if the metric is empty.

impl<S, M, C> TypedMetric for Family<S, M, C>

where M: TypedMetric,

const TYPE: MetricType = <M as TypedMetric>::TYPE

The OpenMetrics metric type.