Struct prometheus_client::registry::Registry

pub struct Registry<M = Box<dyn SendEncodeMetric>> { /* private fields */ }

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 via Registry::iter.

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.
//
// Note the angle brackets to make sure to use the default (dynamic
// dispatched boxed metric) for the generic type parameter.
let mut registry = <Registry>::default();

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

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

Implementations

impl<M> Registry<M>

pub fn register<N: Into<String>, H: Into<String>>(
    &mut self,
    name: N,
    help: H,
    metric: M
)

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<Counter> = Registry::default();
let counter = Counter::default();

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

pub fn register_with_unit<N: Into<String>, H: Into<String>>(
    &mut self,
    name: N,
    help: H,
    unit: Unit,
    metric: M
)

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<Counter> = Registry::default();
let counter = Counter::default();

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

pub fn sub_registry_with_prefix<P: AsRef<str>>(
    &mut self,
    prefix: P
) -> &mut Self

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<Counter> = Registry::default();

let subsystem_a_counter_1 = Counter::default();
let subsystem_a_counter_2 = 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::default();
let subsystem_b_counter_2 = 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 Self

Like Registry::sub_registry_with_prefix but with a label instead.

pub fn iter(&self) -> RegistryIterator<'_, M>

Trait Implementations

impl<M> Default for Registry<M>

fn default() -> Self

Returns the “default value” for a type.