Struct LogHistogramBuilder

pub struct LogHistogramBuilder { /* private fields */ }

Available on tokio_unstable and crate feature rt only.

Configuration for a LogHistogram

The log-scaled histogram implements an H2 histogram where the first bucket covers the range from 0 to LogHistogramBuilder::min_value and the final bucket covers LogHistogramBuilder::max_value to infinity. The precision is bounded to the specified LogHistogramBuilder::max_error. Specifically, the precision is the next smallest value of 2^-p such that it is smaller than the requested max error. You can also select p directly with LogHistogramBuilder::precision_exact.

Depending on the selected parameters, the number of buckets required is variable. To ensure that the histogram size is acceptable, callers may call LogHistogramBuilder::max_buckets. If the resulting histogram would require more buckets, then the method will return an error.

Default values

The default configuration provides the following settings:

1. min_value: 100ns
2. max_value: 68 seconds. The final bucket covers all values >68 seconds
3. precision: max error of 25%

This uses 237 64-bit buckets.

Implementations

impl LogHistogramBuilder

pub fn max_error(self, max_error: f64) -> Self

Set the precision for this histogram

This function determines the smallest value of p that would satisfy the requested precision such that 2^-p is less than precision. To set p directly, use LogHistogramBuilder::precision_exact.

Precision controls the size of the “bucket groups” (consecutive buckets with identical ranges). When p is 0, each bucket will be twice the size of the previous bucket. To match the behavior of the legacy log histogram implementation, use builder.precision_exact(0).

The default value is 25% (2^-2)

The highest supported precision is 0.0977% (2^-10). Provided values less than this will be truncated.

Panics

• max_error < 0
• max_error > 1

pub fn precision_exact(self, p: u32) -> Self

Sets the precision of this histogram directly.

The precision (meaning: the ratio n/bucket_range(n) for some given n) will be 2^-p.

Precision controls the number consecutive buckets with identically sized ranges. When p is 0, each bucket will be twice the size of the previous bucket (bucket groups are only a single bucket wide).

To match the behavior of the legacy implementation (HistogramScale::Log), use builder.precision_exact(0).

Panics

• p > 10

pub fn min_value(self, duration: Duration) -> Self

Sets the minimum duration that can be accurately stored by this histogram.

This sets the resolution. The first bucket will be no larger than the provided duration. Setting this value will reduce the number of required buckets, sometimes quite significantly.

pub fn max_value(self, duration: Duration) -> Self

Sets the maximum value that can by this histogram without truncation

Values greater than this fall in the final bucket that stretches to u64::MAX.

Panics

The provided value is 0

pub fn max_buckets( &mut self, max_buckets: usize, ) -> Result<LogHistogram, InvalidHistogramConfiguration>

Builds the log histogram, enforcing the max buckets requirement

pub fn build(&self) -> LogHistogram

Builds the log histogram

Trait Implementations

impl Clone for LogHistogramBuilder

fn clone(&self) -> LogHistogramBuilder

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for LogHistogramBuilder

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

Formats the value using the given formatter.

impl Default for LogHistogramBuilder

fn default() -> LogHistogramBuilder

Returns the “default value” for a type.

impl From<LogHistogramBuilder> for LogHistogram

fn from(value: LogHistogramBuilder) -> Self

Converts to this type from the input type.

impl Copy for LogHistogramBuilder