Struct metrics_util::registry::Registry

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

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 K: Clone + Eq + Hashable, 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 get_or_create_counter<O, V>(&self, key: &K, op: O) -> Vwhere 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) -> Vwhere 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) -> Vwhere 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 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 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 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.