Struct Histogram

pub struct Histogram { /* private fields */ }

Instance of a Histogram.

Implementations

impl Histogram

pub fn init( lowest_trackable_value: u64, highest_trackable_value: u64, significant_figures: u32, ) -> Result<Histogram>

Create a new Histogram instance. lowest_trackable_value..highest_trackable_value defines the range of values in the Histogram. lowest_trackable_value must be >= 1. significant_figures defines the precision, and must be in the range 1..5.

HistogramErr is the catch-all failure case. It doesn’t report much detail because the underlying library doesn’t.

Example

let mut h = Histogram::init(1, 100000, 2).unwrap();
h.record_value(10);  // record a single count of '10'

pub fn reset(&mut self)

Zero all histogram state in place.

pub fn record_value(&mut self, value: u64) -> bool

Record a specific value. Returns true if successful.

h.record_value(5);
assert_eq!(h.total_count(), 1);

pub fn record_values(&mut self, value: u64, count: u64) -> bool

Record multiple counts of a specific value. Returns true if successful.

h.record_values(5, 10);
assert_eq!(h.total_count(), 10);

pub fn record_corrected_value( &mut self, value: u64, expected_interval: u64, ) -> bool

Record a value, correcting for coordinated omission. This should be used when accumulating latency measurements taked on a regular timebase (expected_interval). Any latency that’s well above that interval implies some kind of outage in which sampled were lost. This corrects for those lost samples to preserve the integrity of the overall statistics.

pub fn record_corrected_values( &mut self, value: u64, count: u64, expected_interval: u64, ) -> bool

As with record_corrected_value() but multiple counts of the value.

pub fn add(&mut self, other: &Histogram) -> u64

Sum two histograms, modifying self in place. Returns the number of samples dropped; samples will be dropped if they’re out of the range lowest_trackable_value .. highest_trackable_value.

pub fn add_while_correcting_for_coordinated_omission( &mut self, other: &Histogram, expected_interval: u64, ) -> u64

As with add but corrects of potential lost samples while doing periodic latency measurements, as in record_corrected_value. Only one correction should be applied.

pub fn total_count(&self) -> u64

Total of all counters

pub fn min(&self) -> u64

Smallest recorded value.

h.record_value(1);
h.record_value(5);
assert_eq!(h.min(), 1);

pub fn max(&self) -> u64

Largest recorded value.

h.record_value(1);
h.record_value(5);
assert_eq!(h.max(), 5);

pub fn value_at_percentile(&self, percentile: f64) -> u64

Value at a particular percentile (0-100).

h.record_values(20, 10);
h.record_value(40);
assert_eq!(h.value_at_percentile(50.0), 20);
assert_eq!(h.value_at_percentile(99.0), 40);

pub fn stddev(&self) -> f64

Standard deviation of values.

pub fn mean(&self) -> f64

Mean of values.

pub fn values_are_equivalent(&self, a: u64, b: u64) -> bool

Returns true if two values are the same according to the lowest, highest and significant figures parameters.

pub fn lowest_equivalent_value(&self, value: u64) -> u64

Lowest value equivalent to the given value.

pub fn count_at_value(&self, value: u64) -> u64

Count for a specific value.

pub fn linear_iter<'a>(&'a self, value_units_per_bucket: u64) -> LinearIter<'a>

Linear iterator over values. Results are returned in equally weighted buckets.

let mut h = Histogram::init(1, 100000, 3).unwrap();
for i in 1..100 { h.record_values(i, i); }
for (i, c) in h.linear_iter(1).enumerate() {    // 100 buckets
    println!("bucket {} = {}", i, c.count_added_in_this_iteration_step);
}

pub fn log_iter<'a>( &'a self, value_units_per_bucket: u64, log_base: f64, ) -> LogIter<'a>

Logarithmic iterator over values. Results are returned in logarithmically weighted buckets.

pub fn recorded_iter<'a>(&'a self) -> RecordedIter<'a>

Iterator over recorded values.

pub fn percentile_iter<'a>( &'a self, ticks_per_half_distance: u32, ) -> PercentileIter<'a>

Iterator over percentiles.

pub fn encode(&self) -> Result<String>

Encode Histogram state into a Base64 encoded string.

pub fn decode(base64: &String) -> Result<Histogram>

Decode Histogram state from a Base64 string generated by encode.

Trait Implementations

impl Clone for Histogram

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Drop for Histogram

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Histogram