Struct metrics_prometheus::recorder::Builder

pub struct Builder<FailureStrategy = PanicInDebugNoOpInRelease, Layers = Stack> { /* private fields */ }

Builder for building a Recorder.

Implementations

impl<S, L> Builder<S, L>

pub fn with_registry<'r>(self, registry: impl IntoCow<'r, Registry>) -> Self

Sets the provided prometheus::Registry to be used by the built Recorder.

When not specified, the prometheus::default_registry() is used by default.

Warning

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

Example

let custom = prometheus::Registry::new_custom(Some("my".into()), None)?;

metrics_prometheus::Recorder::builder()
    .with_registry(&custom)
    .build_and_install();

metrics::increment_counter!("count");

let report =
    prometheus::TextEncoder::new().encode_to_string(&custom.gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP my_count count
# TYPE my_count counter
my_count 1
    "#
    .trim(),
);

pub fn with_failure_strategy<F>(self, strategy: F) -> Builder<F, L>where F: Strategy,

Sets the provided failure::Strategy to be used by the built Recorder.

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 the Recorder to return a no-op metric instead (see metrics::Counter::noop() for example).

The default failure::Strategy is PanicInDebugNoOpInRelease. See failure::strategy module for other available failure::Strategys, or provide your own one by implementing the failure::Strategy trait.

Example

use metrics_prometheus::failure::strategy;

metrics_prometheus::Recorder::builder()
    .with_failure_strategy(strategy::NoOp)
    .build_and_install();

metrics::increment_counter!("invalid.name");

let stats = prometheus::default_registry().gather();
assert_eq!(stats.len(), 0);

pub fn try_with_metric<M>(self, metric: M) -> Result<Self>where M: Bundled + Collector, <M as Bundled>::Bundle: Collector + Clone + 'static, Mutable: Get<Collection<<M as Bundled>::Bundle>>,

Tries to register the provided prometheus metric in the underlying prometheus::Registry in the way making it usable via the created 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 gauge = prometheus::Gauge::new("value", "help")?;

metrics_prometheus::Recorder::builder()
    .try_with_metric(gauge.clone())?
    .build_and_install();

gauge.inc();

let report = prometheus::TextEncoder::new()
    .encode_to_string(&prometheus::default_registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP value help
# TYPE value gauge
value 1
    "#
    .trim(),
);

metrics::increment_gauge!("value", 1.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 2
    "#
    .trim(),
);

pub fn with_metric<M>(self, metric: M) -> Selfwhere M: Bundled + Collector, <M as Bundled>::Bundle: Collector + Clone + 'static, Mutable: Get<Collection<<M as Bundled>::Bundle>>,

Registers the provided prometheus metric in the underlying prometheus::Registry in the way making it usable via the created 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 counter = prometheus::IntCounter::new("value", "help")?;

metrics_prometheus::Recorder::builder()
    .with_metric(counter.clone())
    .build_and_install();

counter.inc();

let report = prometheus::TextEncoder::new()
    .encode_to_string(&prometheus::default_registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP value help
# TYPE value counter
value 1
    "#
    .trim(),
);

metrics::increment_counter!("value");

let report = prometheus::TextEncoder::new()
    .encode_to_string(&prometheus::default_registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP value help
# TYPE value counter
value 2
    "#
    .trim(),
);

pub fn build(self) -> <L as Layer<Recorder<S>>>::Outputwhere S: Strategy, L: Layer<Recorder<S>>,

Builds a Recorder out of this Builder and returns it being wrapped into all the provided metrics::Layers.

Usage

Use this method if you want to:

• either install the built Recorder as metrics::recorder() manually;
• or to compose the built Recorder with some other metrics::Recorders (like being able to write into multiple prometheus::Registrys via metrics::layer::Fanout, for example).

Otherwise, consider using the build_and_install() method instead.

pub fn build_freezable(self) -> <L as Layer<Recorder<S>>>::Outputwhere S: Strategy, L: Layer<Recorder<S>>,

Builds a FreezableRecorder out of this Builder and returns it being wrapped into all the provided metrics::Layers.

Usage

Use this method if you want to:

• either install the built FreezableRecorder as metrics::recorder() manually;
• or to compose the built FreezableRecorder with some other metrics::Recorders (like being able to write into multiple prometheus::Registrys via metrics::layer::Fanout, for example).

Otherwise, consider using the build_freezable_and_install() method instead.

pub fn build_frozen(self) -> <L as Layer<Recorder<S>>>::Outputwhere S: Strategy, L: Layer<Recorder<S>>,

Builds a FrozenRecorder out of this Builder and returns it being wrapped into all the provided metrics::Layers.

Usage

Use this method if you want to:

• either install the built FrozenRecorder as metrics::recorder() manually;
• or to compose the built FrozenRecorder with some other metrics::Recorders (like being able to write into multiple prometheus::Registrys via metrics::layer::Fanout, for example).

Otherwise, consider using the build_frozen_and_install() method instead.

pub fn try_build_and_install(self) -> Result<Recorder<S>, SetRecorderError>where S: Strategy + Clone, L: Layer<Recorder<S>>, <L as Layer<Recorder<S>>>::Output: Recorder + 'static,

Builds a Recorder out of this Builder and tries to install it as metrics::recorder().

Errors

If the built Recorder fails to be installed as metrics::recorder().

Example

use metrics_prometheus::{failure::strategy, recorder};
use metrics_util::layers::FilterLayer;

let custom = prometheus::Registry::new_custom(Some("my".into()), None)?;

let res = metrics_prometheus::Recorder::builder()
    .with_registry(&custom)
    .with_metric(prometheus::IntCounter::new("count", "help")?)
    .with_metric(prometheus::Gauge::new("value", "help")?)
    .with_failure_strategy(strategy::Panic)
    .with_layer(FilterLayer::from_patterns(["ignored"]))
    .try_build_and_install();
assert!(res.is_ok(), "cannot install `Recorder`: {}", res.unwrap_err());

metrics::increment_counter!("count");
metrics::increment_gauge!("value", 3.0);
metrics::histogram!("histo", 38.0);
metrics::histogram!("ignored_histo", 1.0);

let report =
    prometheus::TextEncoder::new().encode_to_string(&custom.gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP my_count help
# TYPE my_count counter
my_count 1
# HELP my_histo histo
# TYPE my_histo histogram
my_histo_bucket{le="0.005"} 0
my_histo_bucket{le="0.01"} 0
my_histo_bucket{le="0.025"} 0
my_histo_bucket{le="0.05"} 0
my_histo_bucket{le="0.1"} 0
my_histo_bucket{le="0.25"} 0
my_histo_bucket{le="0.5"} 0
my_histo_bucket{le="1"} 0
my_histo_bucket{le="2.5"} 0
my_histo_bucket{le="5"} 0
my_histo_bucket{le="10"} 0
my_histo_bucket{le="+Inf"} 1
my_histo_sum 38
my_histo_count 1
# HELP my_value help
# TYPE my_value gauge
my_value 3
    "#
    .trim(),
);

pub fn try_build_freezable_and_install( self ) -> Result<Recorder<S>, SetRecorderError>where S: Strategy + Clone, L: Layer<Recorder<S>>, <L as Layer<Recorder<S>>>::Output: Recorder + 'static,

Builds a FreezableRecorder out of this Builder and tries to install it as metrics::recorder().

Errors

If the built FreezableRecorder fails to be installed as metrics::recorder().

Example

use metrics_prometheus::{failure::strategy, recorder};
use metrics_util::layers::FilterLayer;

let custom = prometheus::Registry::new_custom(Some("my".into()), None)?;

let res = metrics_prometheus::Recorder::builder()
    .with_registry(&custom)
    .with_metric(prometheus::IntCounter::new("count", "help")?)
    .with_failure_strategy(strategy::Panic)
    .with_layer(FilterLayer::from_patterns(["ignored"]))
    .try_build_freezable_and_install();
assert!(
    res.is_ok(),
    "cannot install `FreezableRecorder`: {}",
    res.unwrap_err(),
);

metrics::increment_gauge!("value", 3.0);
metrics::increment_gauge!("ignored_value", 1.0);

res.unwrap().freeze();

metrics::increment_counter!("count");
metrics::increment_gauge!("value", 4.0);

let report =
    prometheus::TextEncoder::new().encode_to_string(&custom.gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP my_count help
# TYPE my_count counter
my_count 1
# HELP my_value value
# TYPE my_value gauge
my_value 7
    "#
    .trim(),
);

pub fn try_build_frozen_and_install(self) -> Result<Registry, SetRecorderError>where S: Strategy + Clone, L: Layer<Recorder<S>>, <L as Layer<Recorder<S>>>::Output: Recorder + 'static,

Builds a FrozenRecorder out of this Builder and tries to install it as metrics::recorder().

Returns the prometheus::Registry backing the installed FrozenRecorder, as there is nothing you can configure with the installed FrozenRecorder itself. For usage as metrics::Recorder, get it via metrics::recorder() directly.

Errors

If the built FrozenRecorder fails to be installed as metrics::recorder().

Example

use metrics_prometheus::{failure::strategy, recorder};
use metrics_util::layers::FilterLayer;

let custom = prometheus::Registry::new_custom(Some("my".into()), None)?;

let res = metrics_prometheus::Recorder::builder()
    .with_registry(&custom)
    .with_metric(prometheus::IntCounter::new("count", "help")?)
    .with_metric(prometheus::Gauge::new("value", "help")?)
    .with_metric(prometheus::Gauge::new("ignored_value", "help")?)
    .with_failure_strategy(strategy::Panic)
    .with_layer(FilterLayer::from_patterns(["ignored"]))
    .try_build_frozen_and_install();
assert!(
    res.is_ok(),
    "cannot install `FrozenRecorder`: {}",
    res.unwrap_err(),
);

metrics::increment_counter!("count");
metrics::increment_gauge!("value", 3.0);
metrics::increment_gauge!("ignored_value", 1.0);

let report =
    prometheus::TextEncoder::new().encode_to_string(&custom.gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP my_count help
# TYPE my_count counter
my_count 1
# HELP my_ignored_value help
# TYPE my_ignored_value gauge
my_ignored_value 0
# HELP my_value help
# TYPE my_value gauge
my_value 3
    "#
    .trim(),
);

pub fn build_and_install(self) -> Recorder<S>where S: Strategy + Clone, L: Layer<Recorder<S>>, <L as Layer<Recorder<S>>>::Output: Recorder + 'static,

Builds a Recorder out of this Builder and installs it as metrics::recorder().

Panics

If the built Recorder fails to be installed as metrics::recorder().

Example

use metrics_prometheus::{failure::strategy, recorder};
use metrics_util::layers::FilterLayer;

let custom = prometheus::Registry::new_custom(Some("my".into()), None)?;

let recorder = metrics_prometheus::Recorder::builder()
    .with_registry(custom)
    .with_metric(prometheus::IntCounter::new("count", "help")?)
    .with_metric(prometheus::Gauge::new("value", "help")?)
    .with_failure_strategy(strategy::Panic)
    .with_layer(FilterLayer::from_patterns(["ignored"]))
    .build_and_install();

metrics::increment_counter!("count");
metrics::increment_gauge!("value", 3.0);
metrics::histogram!("histo", 38.0);
metrics::histogram!("ignored_histo", 1.0);

let report = prometheus::TextEncoder::new()
    .encode_to_string(&recorder.registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP my_count help
# TYPE my_count counter
my_count 1
# HELP my_histo histo
# TYPE my_histo histogram
my_histo_bucket{le="0.005"} 0
my_histo_bucket{le="0.01"} 0
my_histo_bucket{le="0.025"} 0
my_histo_bucket{le="0.05"} 0
my_histo_bucket{le="0.1"} 0
my_histo_bucket{le="0.25"} 0
my_histo_bucket{le="0.5"} 0
my_histo_bucket{le="1"} 0
my_histo_bucket{le="2.5"} 0
my_histo_bucket{le="5"} 0
my_histo_bucket{le="10"} 0
my_histo_bucket{le="+Inf"} 1
my_histo_sum 38
my_histo_count 1
# HELP my_value help
# TYPE my_value gauge
my_value 3
    "#
    .trim(),
);

pub fn build_freezable_and_install(self) -> Recorder<S>where S: Strategy + Clone, L: Layer<Recorder<S>>, <L as Layer<Recorder<S>>>::Output: Recorder + 'static,

Builds a FreezableRecorder out of this Builder and installs it as metrics::recorder().

Panics

If the built FreezableRecorder fails to be installed as metrics::recorder().

Example

use metrics_prometheus::{failure::strategy, recorder};
use metrics_util::layers::FilterLayer;

let custom = prometheus::Registry::new_custom(Some("my".into()), None)?;

let recorder = metrics_prometheus::Recorder::builder()
    .with_registry(&custom)
    .with_metric(prometheus::IntCounter::new("count", "help")?)
    .with_failure_strategy(strategy::Panic)
    .with_layer(FilterLayer::from_patterns(["ignored"]))
    .build_freezable_and_install();

metrics::increment_gauge!("value", 3.0);
metrics::increment_gauge!("ignored_value", 1.0);

recorder.freeze();

metrics::increment_counter!("count");
metrics::increment_gauge!("value", 4.0);

let report =
    prometheus::TextEncoder::new().encode_to_string(&custom.gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP my_count help
# TYPE my_count counter
my_count 1
# HELP my_value value
# TYPE my_value gauge
my_value 7
    "#
    .trim(),
);

pub fn build_frozen_and_install(self) -> Registrywhere S: Strategy + Clone, L: Layer<Recorder<S>>, <L as Layer<Recorder<S>>>::Output: Recorder + 'static,

Builds a FrozenRecorder out of this Builder and installs it as metrics::recorder().

Returns the prometheus::Registry backing the installed FrozenRecorder, as there is nothing you can configure with the installed FrozenRecorder itself. For usage as metrics::Recorder, get it via metrics::recorder() directly.

Panics

If the built FrozenRecorder fails to be installed as metrics::recorder().

Example

use metrics_prometheus::{failure::strategy, recorder};
use metrics_util::layers::FilterLayer;

let custom = prometheus::Registry::new_custom(Some("my".into()), None)?;

metrics_prometheus::Recorder::builder()
    .with_registry(&custom)
    .with_metric(prometheus::IntCounter::new("count", "help")?)
    .with_metric(prometheus::Gauge::new("value", "help")?)
    .with_metric(prometheus::Gauge::new("ignored_value", "help")?)
    .with_failure_strategy(strategy::Panic)
    .with_layer(FilterLayer::from_patterns(["ignored"]))
    .build_frozen_and_install();

metrics::increment_counter!("count");
metrics::increment_gauge!("value", 3.0);
metrics::increment_gauge!("ignored_value", 1.0);

let report =
    prometheus::TextEncoder::new().encode_to_string(&custom.gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP my_count help
# TYPE my_count counter
my_count 1
# HELP my_ignored_value help
# TYPE my_ignored_value gauge
my_ignored_value 0
# HELP my_value help
# TYPE my_value gauge
my_value 3
    "#
    .trim(),
);

impl<S, H, T> Builder<S, Stack<H, T>>

pub fn with_layer<L>(self, layer: L) -> Builder<S, Stack<L, Stack<H, T>>>where L: Layer<<Stack<H, T> as Layer<Recorder<S>>>::Output>, Stack<H, T>: Layer<Recorder<S>>,

Adds the provided metrics::Layer to wrap the built Recorder upon its installation as metrics::recorder().

Example

use metrics_util::layers::FilterLayer;

metrics_prometheus::Recorder::builder()
    .with_layer(FilterLayer::from_patterns(["ignored"]))
    .with_layer(FilterLayer::from_patterns(["skipped"]))
    .build_and_install();

metrics::increment_counter!("ignored_counter");
metrics::increment_counter!("reported_counter");
metrics::increment_counter!("skipped_counter");

let report = prometheus::TextEncoder::new()
    .encode_to_string(&prometheus::default_registry().gather())?;
assert_eq!(
    report.trim(),
    r#"
# HELP reported_counter reported_counter
# TYPE reported_counter counter
reported_counter 1
    "#
    .trim(),
);

Trait Implementations

impl<FailureStrategy: Debug, Layers: Debug> Debug for Builder<FailureStrategy, Layers>

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

Formats the value using the given formatter.