Struct Histogram 

pub struct Histogram { /* private fields */ }

A fixed-bucket histogram for tracking latencies and payload sizes.

All operations are O(BUCKET_COUNT) and allocation free.

Implementations

impl Histogram

pub const OVERFLOW_SENTINEL: u64 = u64::MAX

Sentinel value returned by Histogram::percentile, Histogram::mean, and Histogram::max when the overflow bucket is non-empty.

pub fn new() -> Self

Construct a fresh histogram with all bucket counts set to zero.

Examples

use dynomite::stats::Histogram;
let h = Histogram::new();
assert_eq!(h.count(), 0);

pub fn record(&mut self, val: u64)

Record a single observation, placing it in the appropriate bucket.

Values larger than the largest bucket offset land in the final bucket and signal histogram overflow. Once the overflow bucket is non-empty, Histogram::percentile, Histogram::mean, and Histogram::max all return Histogram::OVERFLOW_SENTINEL.

Examples

use dynomite::stats::Histogram;
let mut h = Histogram::new();
h.record(42);
assert_eq!(h.count(), 1);
assert_eq!(h.max(), 42);

pub fn is_overflowing(&self) -> bool

Returns true when the final (overflow) bucket is non-empty.

The reference implementation logs an error and refuses to publish quantiles in this case; the Rust port surfaces the same signal through this method and through the Histogram::OVERFLOW_SENTINEL returned from quantile accessors.

Examples

use dynomite::stats::Histogram;
let mut h = Histogram::new();
h.record(10);
assert!(!h.is_overflowing());

pub fn count(&self) -> u64

Total number of observations recorded.

Examples

use dynomite::stats::Histogram;
let mut h = Histogram::new();
h.record(1);
h.record(2);
assert_eq!(h.count(), 2);

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

Approximate percentile, where p is in the closed interval [0.0, 1.0]. Inputs outside the range or NaN return 0.

The result is the offset of the first bucket whose cumulative count meets or exceeds floor(count * p). Returns Histogram::OVERFLOW_SENTINEL if the histogram is Histogram::is_overflowing.

Examples

use dynomite::stats::Histogram;
let mut h = Histogram::new();
for v in 0..1_000 { h.record(v); }
assert!(h.percentile(0.95) >= h.percentile(0.5));

pub fn mean(&self) -> f64

Arithmetic mean of all observations using bucket offsets as representative values. Returns 0.0 for an empty histogram and f64::INFINITY when the histogram is Histogram::is_overflowing.

Examples

use dynomite::stats::Histogram;
let mut h = Histogram::new();
h.record(10);
assert!(h.mean() > 0.0);

pub fn max(&self) -> u64

Maximum observation seen since the last Histogram::reset. Returns Histogram::OVERFLOW_SENTINEL when the histogram is Histogram::is_overflowing.

Examples

use dynomite::stats::Histogram;
let mut h = Histogram::new();
h.record(99);
assert_eq!(h.max(), 99);

pub fn reset(&mut self)

Reset all bucket counts and the recorded maximum to zero.

Examples

use dynomite::stats::Histogram;
let mut h = Histogram::new();
h.record(7);
h.reset();
assert_eq!(h.count(), 0);

pub fn merge(&mut self, other: &Self)

Merge bucket counts from another histogram into this one.

The maximum is updated to the larger of the two recorded maxima.

Examples

use dynomite::stats::Histogram;
let mut a = Histogram::new();
let mut b = Histogram::new();
a.record(10);
b.record(20);
a.merge(&b);
assert_eq!(a.count(), 2);
assert_eq!(a.max(), 20);

pub fn buckets(&self) -> &[u64; 94]

Borrow the raw bucket counts.

Examples

use dynomite::stats::{Histogram, BUCKET_COUNT};
let h = Histogram::new();
assert_eq!(h.buckets().len(), BUCKET_COUNT);

Trait Implementations

impl Clone for Histogram

fn clone(&self) -> Histogram

Returns a duplicate 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 Default for Histogram

fn default() -> Self

Returns the “default value” for a type.