Struct Registry

pub struct Registry<K, S>
where
    S: Storage<K>,
{ /* private fields */ }

Available on crate feature registry only.

A high-performance metric registry.

Registry provides the ability to maintain a central listing of metrics mapped by a given key. Metrics themselves are stored in the objects returned by S.

Using Registry as the basis of an exporter

As a reusable building blocking for building exporter implementations, users should look at Key and AtomicStorage to use for their key and storage, respectively.

These two implementations provide behavior that is suitable for most exporters, providing seamless integration with the existing key type used by the core Recorder trait, as well as atomic storage for metrics.

In some cases, users may prefer GenerationalAtomicStorage when know if a metric has been touched, even if its value has not changed since the last time it was observed, is necessary.

Performance

Registry is optimized for reads.

Implementations

impl Registry<Key, AtomicStorage>

pub fn atomic() -> Self

Creates a new Registry using a regular Key and atomic storage.

impl<K, S> Registry<K, S>

where S: Storage<K>,

pub fn new(storage: S) -> Self

Creates a new Registry.

pub fn clear(&self)

Removes all metrics from the registry.

This operation is eventually consistent: metrics will be removed piecemeal, and this method does not ensure that callers will see the registry as entirely empty at any given point.

pub fn visit_counters<F>(&self, collect: F)

where F: FnMut(&K, &S::Counter),

Visits every counter stored in this registry.

This operation does not lock the entire registry, but proceeds directly through the “subshards” that are kept internally. As a result, all subshards will be visited, but a metric that existed at the exact moment that visit_counters was called may not actually be observed if it is deleted before that subshard is reached. Likewise, a metric that is added after the call to visit_counters, but before visit_counters finishes, may also not be observed.

pub fn visit_gauges<F>(&self, collect: F)

where F: FnMut(&K, &S::Gauge),

Visits every gauge stored in this registry.

This operation does not lock the entire registry, but proceeds directly through the “subshards” that are kept internally. As a result, all subshards will be visited, but a metric that existed at the exact moment that visit_gauges was called may not actually be observed if it is deleted before that subshard is reached. Likewise, a metric that is added after the call to visit_gauges, but before visit_gauges finishes, may also not be observed.

pub fn visit_histograms<F>(&self, collect: F)

where F: FnMut(&K, &S::Histogram),

Visits every histogram stored in this registry.

This operation does not lock the entire registry, but proceeds directly through the “subshards” that are kept internally. As a result, all subshards will be visited, but a metric that existed at the exact moment that visit_histograms was called may not actually be observed if it is deleted before that subshard is reached. Likewise, a metric that is added after the call to visit_histograms, but before visit_histograms finishes, may also not be observed.

pub fn retain_counters<F>(&self, f: F)

where F: FnMut(&K, &S::Counter) -> bool,

Retains only counters specified by the predicate.

Remove all counters for which f(&k, &c) returns false. This operation proceeds through the “subshards” in the same way as visit_counters.

pub fn retain_gauges<F>(&self, f: F)

where F: FnMut(&K, &S::Gauge) -> bool,

Retains only gauges specified by the predicate.

Remove all gauges for which f(&k, &g) returns false. This operation proceeds through the “subshards” in the same way as visit_gauges.

pub fn retain_histograms<F>(&self, f: F)

where F: FnMut(&K, &S::Histogram) -> bool,

Retains only histograms specified by the predicate.

Remove all histograms for which f(&k, &h) returns false. This operation proceeds through the “subshards” in the same way as visit_histograms.

impl<K, S> Registry<K, S>

where S: Storage<K>, K: Eq + Hashable,

pub fn delete_counter(&self, key: &K) -> bool

Deletes a counter from the registry.

Returns true if the counter existed and was removed, false otherwise.

pub fn delete_gauge(&self, key: &K) -> bool

Deletes a gauge from the registry.

Returns true if the gauge existed and was removed, false otherwise.

pub fn delete_histogram(&self, key: &K) -> bool

Deletes a histogram from the registry.

Returns true if the histogram existed and was removed, false otherwise.

pub fn get_counter(&self, key: &K) -> Option<S::Counter>

Gets a copy of an existing counter.

pub fn get_gauge(&self, key: &K) -> Option<S::Gauge>

Gets a copy of an existing gauge.

pub fn get_histogram(&self, key: &K) -> Option<S::Histogram>

Gets a copy of an existing histogram.

impl<K, S> Registry<K, S>

where S: Storage<K>, K: Clone + Eq + Hashable,

pub fn get_or_create_counter<O, V>(&self, key: &K, op: O) -> V

where O: FnOnce(&S::Counter) -> V,

Gets or creates the given counter.

The op function will be called for the counter under the given key, with the counter first being created if it does not already exist.

pub fn get_or_create_gauge<O, V>(&self, key: &K, op: O) -> V

where O: FnOnce(&S::Gauge) -> V,

Gets or creates the given gauge.

The op function will be called for the gauge under the given key, with the gauge first being created if it does not already exist.

pub fn get_or_create_histogram<O, V>(&self, key: &K, op: O) -> V

where O: FnOnce(&S::Histogram) -> V,

Gets or creates the given histogram.

The op function will be called for the histogram under the given key, with the histogram first being created if it does not already exist.

pub fn get_counter_handles(&self) -> HashMap<K, S::Counter>

Gets a map of all present counters, mapped by key.

This map is a point-in-time snapshot of the registry.

pub fn get_gauge_handles(&self) -> HashMap<K, S::Gauge>

Gets a map of all present gauges, mapped by key.

This map is a point-in-time snapshot of the registry.

pub fn get_histogram_handles(&self) -> HashMap<K, S::Histogram>

Gets a map of all present histograms, mapped by key.

This map is a point-in-time snapshot of the registry.

Trait Implementations

impl<K: Debug, S> Debug for Registry<K, S>

where S: Storage<K> + Debug, S::Counter: Debug, S::Gauge: Debug, S::Histogram: Debug,

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

Formats the value using the given formatter.