Struct metrics_util::Registry

pub struct Registry<P = StandardPrimitives> where
    P: Primitives,  { /* private fields */ }

A high-performance metric registry.

Registry provides the ability to maintain a central listing of metrics mapped by a given key.

In many cases, K will be a composite key, where the fundamental Key type from metrics is present, and differentiation is provided by storing the metric type alongside.

Metrics themselves are represented opaquely behind H. In most cases, this would be a thread-safe handle to the underlying metrics storage that the owner of the registry can use to update the actual metric value(s) as needed. Handle, from this crate, is a solid default choice.

As well, handles have an associated generation counter which is incremented any time an entry is operated on. This generation is returned with the handle when querying the registry, and can be used in order to delete a handle from the registry, allowing callers to prune old/stale handles over time.

Registry is optimized for reads.

Implementations

impl<P> Registry<P> where
    P: Primitives, 

pub fn new() -> 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: &Key, op: O) -> V where
    O: FnOnce(&P::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: &Key, op: O) -> V where
    O: FnOnce(&P::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: &Key, op: O) -> V where
    O: FnOnce(&P::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: &Key) -> bool

Deletes a counter from the registry.

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

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

Deletes a gauge from the registry.

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

pub fn delete_histogram(&self, key: &Key) -> 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(&Key, &P::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(&Key, &P::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(&Key, &P::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<Key, P::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<Key, P::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<Key, P::Histogram>

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

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