Struct prometheus_client::registry::Registry

pub struct Registry { /* 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.
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>) -> Self

Creates a new default Registry with the given prefix.

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

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: Into<String>, H: Into<String>>(
    &mut self,
    name: N,
    help: H,
    unit: Unit,
    metric: impl Metric
)

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 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::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 Self

Like Registry::sub_registry_with_prefix but with a label instead.

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

Iterator over all metrics registered with the Registry.

Examples found in repository

src/registry.rs (line 265)

    fn next(&mut self) -> Option<Self::Item> {
        if let Some(metric) = self.metrics.next() {
            return Some(metric);
        }

        loop {
            if let Some(metric) = self.sub_registry.as_mut().and_then(|i| i.next()) {
                return Some(metric);
            }

            self.sub_registry = self.sub_registries.next().map(|r| Box::new(r.iter()));

            if self.sub_registry.is_none() {
                break;
            }
        }

        None
    }

src/encoding/text.rs (line 41)

pub fn encode<W>(writer: &mut W, registry: &Registry) -> Result<(), std::fmt::Error>
where
    W: Write,
{
    for (desc, metric) in registry.iter() {
        writer.write_str("# HELP ")?;
        writer.write_str(desc.name())?;
        if let Some(unit) = desc.unit() {
            writer.write_str("_")?;
            writer.write_str(unit.as_str())?;
        }
        writer.write_str(" ")?;
        writer.write_str(desc.help())?;
        writer.write_str("\n")?;

        writer.write_str("# TYPE ")?;
        writer.write_str(desc.name())?;
        if let Some(unit) = desc.unit() {
            writer.write_str("_")?;
            writer.write_str(unit.as_str())?;
        }
        writer.write_str(" ")?;
        writer.write_str(EncodeMetric::metric_type(metric.as_ref()).as_str())?;
        writer.write_str("\n")?;

        if let Some(unit) = desc.unit() {
            writer.write_str("# UNIT ")?;
            writer.write_str(desc.name())?;
            writer.write_str("_")?;
            writer.write_str(unit.as_str())?;
            writer.write_str(" ")?;
            writer.write_str(unit.as_str())?;
            writer.write_str("\n")?;
        }

        let encoder = MetricEncoder {
            writer,
            name: desc.name(),
            unit: desc.unit(),
            const_labels: desc.labels(),
            family_labels: None,
        }
        .into();

        EncodeMetric::encode(metric.as_ref(), encoder)?;
    }

    writer.write_str("# EOF\n")?;

    Ok(())
}

Trait Implementations

impl Debug for Registry

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

Formats the value using the given formatter.

impl Default for Registry

fn default() -> Registry

Returns the “default value” for a type.