Builder

metrics_prometheus::recorder

Struct Builder 

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

Builder for building a Recorder.

Implementations§

Source§

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

Source

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::counter!("count").increment(1);

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(),
);
Source

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::counter!("invalid.name").increment(1);

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

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:

§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::gauge!("value").increment(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(),
);
Source

pub fn with_metric<M>(self, metric: M) -> Self
where 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:

§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::counter!("value").increment(1);

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(),
);
Source

pub fn build(self) -> <L as Layer<Recorder<S>>>::Output
where 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:

Otherwise, consider using the build_and_install() method instead.

Source

pub fn build_freezable(self) -> <L as Layer<Recorder<S>>>::Output
where 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:

Otherwise, consider using the build_freezable_and_install() method instead.

Source

pub fn build_frozen(self) -> <L as Layer<Recorder<S>>>::Output
where 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:

Otherwise, consider using the build_frozen_and_install() method instead.

Source

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

Builds a Recorder out of this Builder and tries to install it with the metrics::set_global_recorder().

§Errors

If the built Recorder fails to be installed with the metrics::set_global_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::counter!("count").increment(1);
metrics::gauge!("value").increment(3.0);
metrics::histogram!("histo").record(38.0);
metrics::histogram!("ignored_histo").record(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(),
);
Source

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

Builds a FreezableRecorder out of this Builder and tries to install it with the metrics::set_global_recorder().

§Errors

If the built FreezableRecorder fails to be installed with the metrics::set_global_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::gauge!("value").increment(3.0);
metrics::gauge!("ignored_value").increment(1.0);

res.unwrap().freeze();

metrics::counter!("count").increment(1);
metrics::gauge!("value").increment(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(),
);
Source

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

Builds a FrozenRecorder out of this Builder and tries to install it with the metrics::set_global_recorder().

Returns the prometheus::Registry backing the installed FrozenRecorder, as there is nothing you can configure with the installed FrozenRecorder itself.

§Errors

If the built FrozenRecorder fails to be installed with the metrics::set_global_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::counter!("count").increment(1);
metrics::gauge!("value").increment(3.0);
metrics::gauge!("ignored_value").increment(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(),
);
Source

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

Builds a Recorder out of this Builder and installs it with the metrics::set_global_recorder().

§Panics

If the built Recorder fails to be installed with the metrics::set_global_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::counter!("count").increment(1);
metrics::gauge!("value").increment(3.0);
metrics::histogram!("histo").record(38.0);
metrics::histogram!("ignored_histo").record(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(),
);
Source

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

Builds a FreezableRecorder out of this Builder and installs it with the metrics::set_global_recorder().

§Panics

If the built FreezableRecorder fails to be installed with the metrics::set_global_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::gauge!("value").increment(3.0);
metrics::gauge!("ignored_value").increment(1.0);

recorder.freeze();

metrics::counter!("count").increment(1);
metrics::gauge!("value").increment(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(),
);
Source

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

Builds a FrozenRecorder out of this Builder and installs it with the metrics::set_global_recorder().

Returns the prometheus::Registry backing the installed FrozenRecorder, as there is nothing you can configure with the installed FrozenRecorder itself.

§Panics

If the built FrozenRecorder fails to be installed with the metrics::set_global_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::counter!("count").increment(1);
metrics::gauge!("value").increment(3.0);
metrics::gauge!("ignored_value").increment(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(),
);
Source§

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

Source

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 with the metrics::set_global_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::counter!("ignored_counter").increment(1);
metrics::counter!("reported_counter").increment(1);
metrics::counter!("skipped_counter").increment(1);

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§

Source§

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

Source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

§

impl<FailureStrategy, Layers> Freeze for Builder<FailureStrategy, Layers>
where FailureStrategy: Freeze, Layers: Freeze,

§

impl<FailureStrategy = PanicInDebugNoOpInRelease, Layers = Stack> !RefUnwindSafe for Builder<FailureStrategy, Layers>

§

impl<FailureStrategy, Layers> Send for Builder<FailureStrategy, Layers>
where FailureStrategy: Send, Layers: Send,

§

impl<FailureStrategy, Layers> Sync for Builder<FailureStrategy, Layers>
where FailureStrategy: Sync, Layers: Sync,

§

impl<FailureStrategy, Layers> Unpin for Builder<FailureStrategy, Layers>
where FailureStrategy: Unpin, Layers: Unpin,

§

impl<FailureStrategy = PanicInDebugNoOpInRelease, Layers = Stack> !UnwindSafe for Builder<FailureStrategy, Layers>

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

Source§

fn vzip(self) -> V