Struct HistogramBuilder

#[non_exhaustive]
pub struct HistogramBuilder<'a, T> {
    pub instrument_provider: &'a dyn InstrumentProvider,
    pub name: Cow<'static, str>,
    pub description: Option<Cow<'static, str>>,
    pub unit: Option<Cow<'static, str>>,
    pub boundaries: Option<Vec<f64>>,
    /* private fields */
}

Configuration for building a Histogram.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

instrument_provider: &'a dyn InstrumentProvider

Instrument provider is used to create the instrument.

name: Cow<'static, str>

Name of the Histogram.

description: Option<Cow<'static, str>>

Description of the Histogram.

unit: Option<Cow<'static, str>>

Unit of the Histogram.

boundaries: Option<Vec<f64>>

Bucket boundaries for the histogram.

Implementations

impl<'a, T> HistogramBuilder<'a, T>

pub fn with_description<S: Into<Cow<'static, str>>>( self, description: S, ) -> Self

Set the description for this instrument

pub fn with_unit<S: Into<Cow<'static, str>>>(self, unit: S) -> Self

Set the unit for this instrument.

Unit is case sensitive(kb is not the same as kB).

Unit must be:

• ASCII string
• No longer than 63 characters

pub fn with_boundaries(self, boundaries: Vec<f64>) -> Self

Set the boundaries for this histogram.

Setting boundaries is optional. By default, the boundaries are set to:

[0.0, 5.0, 10.0, 25.0, 50.0, 75.0, 100.0, 250.0, 500.0, 750.0, 1000.0, 2500.0, 5000.0, 7500.0, 10000.0]

Notes

• Boundaries must not contain f64::NAN, f64::INFINITY or f64::NEG_INFINITY
• Values must be in strictly increasing order (e.g., each value must be greater than the previous).
• Boundaries must not contain duplicate values.

If invalid boundaries are provided, the instrument will not report measurements. Providing an empty vec![] means no bucket information will be calculated.

Warning

Using more buckets can improve the accuracy of percentile calculations in backends. However, this comes at a cost, including increased memory, CPU, and network usage. Choose the number of buckets carefully, considering your application’s performance and resource requirements.

impl<'a> HistogramBuilder<'a, Histogram<f64>>

pub fn build(self) -> Histogram<f64>

Creates a new instrument.

Validates the instrument configuration and creates a new instrument. In case of invalid configuration, a no-op instrument is returned and an error is logged using internal logging.

impl<'a> HistogramBuilder<'a, Histogram<u64>>

pub fn build(self) -> Histogram<u64>

Creates a new instrument.

Validates the instrument configuration and creates a new instrument. In case of invalid configuration, a no-op instrument is returned and an error is logged using internal logging.

Trait Implementations

impl<T> Debug for HistogramBuilder<'_, T>

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

Formats the value using the given formatter.