Struct Histogram

pub struct Histogram { /* private fields */ }

A histogram that uses plain 64bit counters for each bucket.

Implementations

impl Histogram

pub fn new(grouping_power: u8, max_value_power: u8) -> Result<Self, Error>

Construct a new histogram from the provided parameters. See the documentation for crate::Config to understand their meaning.

pub fn with_config(config: &Config) -> Self

Creates a new histogram using a provided crate::Config.

pub fn from_buckets( grouping_power: u8, max_value_power: u8, buckets: Vec<u64>, ) -> Result<Self, Error>

Creates a new histogram using a provided crate::Config and the provided collection of buckets.

pub fn increment(&mut self, value: u64) -> Result<(), Error>

Increment the counter for the bucket corresponding to the provided value by one.

pub fn add(&mut self, value: u64, count: u64) -> Result<(), Error>

Add some count to the counter for the bucket corresponding to the provided value

pub fn as_slice(&self) -> &[u64]

Get a reference to the raw counters.

pub fn as_mut_slice(&mut self) -> &mut [u64]

Get a mutable reference to the raw counters.

pub fn percentiles( &self, percentiles: &[f64], ) -> Result<Option<Vec<(f64, Bucket)>>, Error>

Return a collection of percentiles from this histogram.

Each percentile should be in the inclusive range 0.0..=100.0. For example, the 50th percentile (median) can be found using 50.0.

The results will be sorted by the percentile.

pub fn percentile(&self, percentile: f64) -> Result<Option<Bucket>, Error>

Return a single percentile from this histogram.

The percentile should be in the inclusive range 0.0..=100.0. For example, the 50th percentile (median) can be found using 50.0.

pub fn downsample(&self, grouping_power: u8) -> Result<Histogram, Error>

Returns a new histogram with a reduced grouping power. The reduced grouping power should lie in the range (0..existing grouping power).

The difference in grouping powers determines how much histogram size is reduced by, with every step approximately halving the total number of buckets (and hence total size of the histogram), while doubling the relative error.

This works by iterating over every bucket in the existing histogram and inserting the contained values into the new histogram. While we do not know the exact values of the data points (only that they lie within the bucket’s range), it does not matter since the bucket is not split during downsampling and any value can be used.

pub fn checked_add(&self, other: &Histogram) -> Result<Histogram, Error>

Adds the other histogram to this histogram and returns the result as a new histogram.

An error is returned if the two histograms have incompatible parameters or if there is an overflow.

pub fn wrapping_add(&self, other: &Histogram) -> Result<Histogram, Error>

Adds the other histogram to this histogram and returns the result as a new histogram.

An error is returned if the two histograms have incompatible parameters.

pub fn checked_sub(&self, other: &Histogram) -> Result<Histogram, Error>

Subtracts the other histogram from this histogram and returns the result as a new histogram.

An error is returned if the two histograms have incompatible parameters or if there is an overflow.

pub fn wrapping_sub(&self, other: &Histogram) -> Result<Histogram, Error>

Subtracts the other histogram from this histogram and returns the result as a new histogram.

An error is returned if the two histograms have incompatible parameters.

pub fn config(&self) -> Config

Returns the bucket configuration of the histogram.

Trait Implementations

impl Clone for Histogram

fn clone(&self) -> Histogram

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Histogram

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

Formats the value using the given formatter.

impl From<&Histogram> for SparseHistogram

fn from(histogram: &Histogram) -> Self

Converts to this type from the input type.

impl From<&SparseHistogram> for Histogram

fn from(other: &SparseHistogram) -> Self

Converts to this type from the input type.

impl<'a> IntoIterator for &'a Histogram

type Item = Bucket

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Histogram

fn eq(&self, other: &Histogram) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Histogram

impl StructuralPartialEq for Histogram