Struct Registry

pub struct Registry { /* private fields */ }

Available on crate feature metrics only.

A metric registry.

First off one registers metrics with the registry via Registry::register. Later on the Registry is passed to an encoder collecting samples of each metric by iterating all metrics in the Registry.

Registry is the core building block, generic over the metric type being registered. Out of convenience, the generic type parameter is set to use dynamic dispatching by default to be able to register different types of metrics (e.g. Counter and Gauge) with the same registry. Advanced users might want to use their custom types.

// Create a metric registry.
let mut registry = Registry::default();

let counter: Counter = Counter::default();
let gauge: Gauge = Gauge::default();

registry.register(
  "my_counter",
  "This is my counter",
  counter.clone(),
);
registry.register(
  "my_gauge",
  "This is my gauge",
  gauge.clone(),
);

Implementations

impl Registry

pub fn with_prefix(prefix: impl Into<String>) -> Registry

Creates a new default Registry with the given prefix.

pub fn with_labels( labels: impl Iterator<Item = (Cow<'static, str>, Cow<'static, str>)>, ) -> Registry

Creates a new default Registry with the given labels.

pub fn with_prefix_and_labels( prefix: impl Into<String>, labels: impl Iterator<Item = (Cow<'static, str>, Cow<'static, str>)>, ) -> Registry

Creates a new default Registry with the given prefix and labels.

pub fn register<N, H>(&mut self, name: N, help: H, metric: impl Metric)

where N: Into<String>, H: Into<String>,

Register a metric with the Registry.

Note: In the Open Metrics text exposition format some metric types have a special suffix, e.g. the Counter metric with _total. These suffixes are inferred through the metric type and must not be appended to the metric name manually by the user.

Note: A full stop punctuation mark (.) is automatically added to the passed help text.

Use Registry::register_with_unit whenever a unit for the given metric is known.

let mut registry = Registry::default();
let counter: Counter = Counter::default();

registry.register("my_counter", "This is my counter", counter.clone());

pub fn register_with_unit<N, H>( &mut self, name: N, help: H, unit: Unit, metric: impl Metric, )

where N: Into<String>, H: Into<String>,

Register a metric with the Registry specifying the metric’s unit.

See Registry::register for additional documentation.

Note: In the Open Metrics text exposition format units are appended to the metric name. This is done automatically. Users must not append the unit to the name manually.

let mut registry = Registry::default();
let counter: Counter = Counter::default();

registry.register_with_unit(
  "my_counter",
  "This is my counter",
  Unit::Seconds,
  counter.clone(),
);

pub fn register_collector(&mut self, collector: Box<dyn Collector>)

Register a [Collector].

#[derive(Debug)]
struct MyCollector {}

impl Collector for MyCollector {
    fn encode(&self, mut encoder: DescriptorEncoder) -> Result<(), std::fmt::Error> {
        let counter = ConstCounter::new(42);
        let metric_encoder = encoder.encode_descriptor(
            "my_counter",
            "some help",
            None,
            counter.metric_type(),
        )?;
        counter.encode(metric_encoder)?;
        Ok(())
    }
}

let my_collector = Box::new(MyCollector{});

let mut registry = Registry::default();

registry.register_collector(my_collector);

pub fn sub_registry_with_prefix<P>(&mut self, prefix: P) -> &mut Registry

where P: AsRef<str>,

Create a sub-registry to register metrics with a common prefix.

Say you would like to prefix one set of metrics with subsystem_a and one set of metrics with subsystem_b. Instead of prefixing each metric with the corresponding subsystem string individually, you can create two sub-registries like demonstrated below.

This can be used to pass a prefixed sub-registry down to a subsystem of your architecture automatically adding a prefix to each metric the subsystem registers.

let mut registry = Registry::default();

let subsystem_a_counter_1: Counter = Counter::default();
let subsystem_a_counter_2: Counter = Counter::default();

let subsystem_a_registry = registry.sub_registry_with_prefix("subsystem_a");
registry.register("counter_1", "", subsystem_a_counter_1.clone());
registry.register("counter_2", "", subsystem_a_counter_2.clone());

let subsystem_b_counter_1: Counter = Counter::default();
let subsystem_b_counter_2: Counter = Counter::default();

let subsystem_a_registry = registry.sub_registry_with_prefix("subsystem_b");
registry.register("counter_1", "", subsystem_b_counter_1.clone());
registry.register("counter_2", "", subsystem_b_counter_2.clone());

See Registry::sub_registry_with_label for the same functionality, but namespacing with a label instead of a metric name prefix.

pub fn sub_registry_with_label( &mut self, label: (Cow<'static, str>, Cow<'static, str>), ) -> &mut Registry

Like Registry::sub_registry_with_prefix but with a label instead.

pub fn sub_registry_with_labels( &mut self, labels: impl Iterator<Item = (Cow<'static, str>, Cow<'static, str>)>, ) -> &mut Registry

Like Registry::sub_registry_with_prefix but with multiple labels instead.

Trait Implementations

impl Debug for Registry

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

Formats the value using the given formatter.

impl Default for Registry

fn default() -> Registry

Returns the “default value” for a type.