Struct metrics_prometheus::Recorder

pub struct Recorder<FailureStrategy = PanicInDebugNoOpInRelease> { /* private fields */ }

metrics::Recorder registering metrics in a prometheus::Registry and powered by a metrics::Registry built on top of a storage::Mutable.

This Recorder is capable of registering metrics in its prometheus::Registry on the fly. By default, the prometheus::default_registry() is used.

Example

let recorder = metrics_prometheus::must_install();

// Either use `metrics` crate interfaces.
metrics::increment_counter!("count", "whose" => "mine", "kind" => "owned");
metrics::increment_counter!("count", "whose" => "mine", "kind" => "ref");
metrics::increment_counter!("count", "kind" => "owned", "whose" => "dummy");

// Or construct and provide `prometheus` metrics directly.
recorder.register_metric(prometheus::Gauge::new("value", "help")?)?;

let report = prometheus::TextEncoder::new()
    .encode_to_string(&prometheus::default_registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP count count
# TYPE count counter
count{kind="owned",whose="dummy"} 1
count{kind="owned",whose="mine"} 1
count{kind="ref",whose="mine"} 1
# HELP value help
# TYPE value gauge
value 0
    "#
    .trim(),
);

// Metrics can be described anytime after being registered in
// `prometheus::Registry`.
metrics::describe_counter!("count", "Example of counter.");
metrics::describe_gauge!("value", "Example of gauge.");

let report = prometheus::TextEncoder::new()
    .encode_to_string(&recorder.registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP count Example of counter.
# TYPE count counter
count{kind="owned",whose="dummy"} 1
count{kind="owned",whose="mine"} 1
count{kind="ref",whose="mine"} 1
# HELP value Example of gauge.
# TYPE value gauge
value 0
    "#
    .trim(),
);

// Description can be changed multiple times and anytime:
metrics::describe_counter!("count", "Another description.");

// Even before a metric is registered in `prometheus::Registry`.
metrics::describe_counter!("another", "Yet another counter.");
metrics::increment_counter!("another");

let report = prometheus::TextEncoder::new()
    .encode_to_string(&recorder.registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP another Yet another counter.
# TYPE another counter
another 1
# HELP count Another description.
# TYPE count counter
count{kind="owned",whose="dummy"} 1
count{kind="owned",whose="mine"} 1
count{kind="ref",whose="mine"} 1
# HELP value Example of gauge.
# TYPE value gauge
value 0
    "#
    .trim(),
);

Performance

This Recorder has the very same performance characteristics of using metrics via metrics::Recorder interface as the ones provided by a metrics::Registry: for already registered metrics it’s just a read-lock on a sharded HashMap plus Arc cloning.

Errors

prometheus::Registry has far more stricter semantics than the ones implied by a metrics::Recorder. That’s why incorrect usage of prometheus metrics via metrics crate will inevitably lead to a prometheus::Registry returning a prometheus::Error instead of a registering the metric. The returned prometheus::Error can be either turned into a panic, or just silently ignored, making this Recorder to return a no-op metric instead (see metrics::Counter::noop() for example).

The desired behavior can be specified with a failure::Strategy implementation of this Recorder. By default a PanicInDebugNoOpInRelease failure::Strategy is used. See failure::strategy module for other available failure::Strategys, or provide your own one by implementing the failure::Strategy trait.

use metrics_prometheus::failure::strategy;

metrics_prometheus::Recorder::builder()
    .with_failure_strategy(strategy::Panic)
    .must_build_and_install();

metrics::increment_counter!("count", "kind" => "owned");
// This panics, as such labeling is not allowed by `prometheus` crate.
metrics::increment_counter!("count", "whose" => "mine");

Implementations

impl Recorder

pub fn builder() -> Builder

Starts building a new Recorder on top of the prometheus::default_registry().

impl<S> Recorder<S>

pub const fn registry(&self) -> &Registry

Return the underlying prometheus::Registry backing this Recorder.

Warning

Any prometheus metrics, registered directly in the returned prometheus::Registry, cannot be used via this metrics::Recorder (and, so, metrics crate interfaces), and trying to use them will inevitably cause a prometheus::Error being emitted.

use metrics_prometheus::failure::strategy;

let recorder = metrics_prometheus::Recorder::builder()
    .with_failure_strategy(strategy::Panic)
    .must_build_and_install();

let counter = prometheus::IntCounter::new("value", "help")?;
recorder.registry().register(Box::new(counter))?;

// panics: Duplicate metrics collector registration attempted
metrics::increment_counter!("value");

pub fn register_metric<M>(&self, metric: M) -> Result<()>where
    M: Bundled + Collector,
    <M as Bundled>::Bundle: Collector + Clone + 'static,
    Mutable: GetCollection<<M as Bundled>::Bundle>,

Registers the provided prometheus metric in the underlying prometheus::Registry in the way making it usable via this Recorder (and, so, metrics crate interfaces).

Accepts only the following prometheus metrics:

• prometheus::IntCounter, prometheus::IntCounterVec
• prometheus::Gauge, prometheus::GaugeVec
• prometheus::Histogram, prometheus::HistogramVec

Errors

If the underlying prometheus::Registry fails to register the provided metric.

Example

let recorder = metrics_prometheus::must_install();

let counter = prometheus::IntCounterVec::new(
    prometheus::opts!("value", "help"),
    &["whose", "kind"],
)?;

recorder.register_metric(counter.clone())?;

counter.with_label_values(&["mine", "owned"]).inc();
counter.with_label_values(&["foreign", "ref"]).inc_by(2);
counter.with_label_values(&["foreign", "owned"]).inc_by(3);

let report = prometheus::TextEncoder::new()
    .encode_to_string(&prometheus::default_registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP value help
# TYPE value counter
value{kind="owned",whose="foreign"} 3
value{kind="owned",whose="mine"} 1
value{kind="ref",whose="foreign"} 2
    "#
    .trim(),
);

metrics::increment_counter!(
    "value", "whose" => "mine", "kind" => "owned",
);
metrics::increment_counter!(
    "value", "whose" => "mine", "kind" => "ref",
);
metrics::increment_counter!(
    "value", "kind" => "owned", "whose" => "foreign",
);

let report = prometheus::TextEncoder::new()
    .encode_to_string(&prometheus::default_registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP value help
# TYPE value counter
value{kind="owned",whose="foreign"} 4
value{kind="owned",whose="mine"} 2
value{kind="ref",whose="foreign"} 2
value{kind="ref",whose="mine"} 1
    "#
    .trim(),
);

pub fn must_register_metric<M>(&self, metric: M)where
    M: Bundled + Collector,
    <M as Bundled>::Bundle: Collector + Clone + 'static,
    Mutable: GetCollection<<M as Bundled>::Bundle>,

Registers the provided prometheus metric in the underlying prometheus::Registry in the way making it usable via this Recorder (and, so, metrics crate interfaces).

Accepts only the following prometheus metrics:

• prometheus::IntCounter, prometheus::IntCounterVec
• prometheus::Gauge, prometheus::GaugeVec
• prometheus::Histogram, prometheus::HistogramVec

Panics

If the underlying prometheus::Registry fails to register the provided metric.

Example

let recorder = metrics_prometheus::must_install();

let gauge = prometheus::GaugeVec::new(
    prometheus::opts!("value", "help"),
    &["whose", "kind"],
)?;

recorder.must_register_metric(gauge.clone());

gauge.with_label_values(&["mine", "owned"]).inc();
gauge.with_label_values(&["foreign", "ref"]).set(2.0);
gauge.with_label_values(&["foreign", "owned"]).set(3.0);

let report = prometheus::TextEncoder::new()
    .encode_to_string(&prometheus::default_registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP value help
# TYPE value gauge
value{kind="owned",whose="foreign"} 3
value{kind="owned",whose="mine"} 1
value{kind="ref",whose="foreign"} 2
    "#
    .trim(),
);

metrics::increment_gauge!(
    "value", 2.0, "whose" => "mine", "kind" => "owned",
);
metrics::decrement_gauge!(
    "value", 2.0, "whose" => "mine", "kind" => "ref",
);
metrics::increment_gauge!(
    "value", 2.0, "kind" => "owned", "whose" => "foreign",
);

let report = prometheus::TextEncoder::new()
    .encode_to_string(&prometheus::default_registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP value help
# TYPE value gauge
value{kind="owned",whose="foreign"} 5
value{kind="owned",whose="mine"} 3
value{kind="ref",whose="foreign"} 2
value{kind="ref",whose="mine"} -2
    "#
    .trim(),
);

Trait Implementations

impl<FailureStrategy: Clone> Clone for Recorder<FailureStrategy>

fn clone(&self) -> Recorder<FailureStrategy>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S: Debug> Debug for Recorder<S>

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

Formats the value using the given formatter.

impl<S> Recorder for Recorder<S>where
    S: Strategy,

fn describe_counter(
    &self,
    name: KeyName,
    _: Option<Unit>,
    description: SharedString
)

Describes a counter.

fn describe_gauge(&self, name: KeyName, _: Option<Unit>, description: SharedString)

Describes a gauge.

fn describe_histogram(
    &self,
    name: KeyName,
    _: Option<Unit>,
    description: SharedString
)

Describes a histogram.

fn register_counter(&self, key: &Key) -> Counter

Registers a counter.

fn register_gauge(&self, key: &Key) -> Gauge

Registers a gauge.

fn register_histogram(&self, key: &Key) -> Histogram

Registers a histogram.