exponential-decay-histogram

Documentation

A histogram which exponentially weights in favor of recent values.

License

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

lib.rs:

A histogram which exponentially weights in favor of recent values.

Histograms compute statistics about the distribution of values in a data set. This histogram exponentially favors recent values over older ones, making it suitable for use cases such as monitoring the state of long running processes.

The histogram does not store all values simultaneously, but rather a randomized subset. This allows us to put bounds on overall memory use regardless of the rate of events.

Each sample in the histogram is composed of an i64 value that contributes to the histogram's statistics and an exemplar, which is an arbitrary value that is tracked by the histogram as long the sample is retained. By default, the exemplar type is simply (), but consumers that want to use exemplars can pick a different type and pass it into the histogram with the ExponentialDecayHistogram::update_ex method.

This implementation is based on the ExponentiallyDecayingReservoir class in the Java Metrics library, which is itself based on the forward decay model described in Cormode et al. 2009.

Examples

use exponential_decay_histogram::ExponentialDecayHistogram;

let mut histogram = ExponentialDecayHistogram::new();

// Do some work for a while and fill the histogram with some information.
// Even though we're putting 10000 values into the histogram, it will only
// retain a subset of them.
for _ in 0..10000 {
    let size = do_work();
    histogram.update(size);
}

// Take a snapshot to inspect the current state of the histogram.
let snapshot = histogram.snapshot();
println!("count: {}", snapshot.count());
println!("min: {}", snapshot.min());
println!("max: {}", snapshot.max());
println!("mean: {}", snapshot.mean());
println!("standard deviation: {}", snapshot.stddev());
println!("median: {}", snapshot.value(0.5));
println!("99th percentile: {}", snapshot.value(0.99));