pub struct Heatmap { /* private fields */ }Expand description
A Heatmap stores counts for timestamped values over a configured span of
time.
Internally, it is represented as a ring buffer of histograms with one additional histogram to track all counts within the span of time. Old histograms age-out as time moves forward and they are subtracted from the summary histogram at that point.
This acts as a moving histogram, such that requesting a percentile returns a percentile from across the configured span of time.
Implementations§
source§impl Heatmap
impl Heatmap
sourcepub fn new(
m: u32,
r: u32,
n: u32,
span: Duration,
resolution: Duration
) -> Result<Self, Error>
pub fn new( m: u32, r: u32, n: u32, span: Duration, resolution: Duration ) -> Result<Self, Error>
Create a new Heatmap which stores counts for timestamped values over
a configured span of time.
-
m- sets the minimum resolutionM = 2^m. This is the smallest unit of quantification, which is also the smallest bucket width. If the input values are always integers, choosingm=0would ensure precise recording for the smallest values. -
r- sets the minimum resolution rangeR = 2^r - 1. The selected value must be greater than the minimum resolutionm. This sets the maximum value that the minimum resolution should extend to. -
n- sets the maximum valueN = 2^n - 1. The selected value must be greater than or equal to the minimum resolution ranger. -
span- sets the total duration that the heatmap covers -
resolution- sets the resolution in the time domain. Counts from similar instants in time will be grouped together.
sourcepub fn builder() -> Builder
pub fn builder() -> Builder
Creates a Builder with the default values m = 0, r = 10, n = 30,
span = 60s, resolution = 1s.
This would create a Heatmap with 61 total Histograms, each with
11264 buckets which can store values from 1 to 1_073_741_823 with
values 1 to 1023 being stored in buckets with a width of 1. Such a
Heatmap would be appropriate for latencies measured in nanoseconds
where the max expected latency is one second and reporting covers the
past minute.
sourcepub fn buckets(&self) -> usize
pub fn buckets(&self) -> usize
Returns the number of buckets stored within each Histogram in the
Heatmap
sourcepub fn increment(&self, time: Instant, value: u64, count: u32)
pub fn increment(&self, time: Instant, value: u64, count: u32)
Increment a time-value pair by a specified count
sourcepub fn percentile(&self, percentile: f64) -> Result<Bucket, Error>
pub fn percentile(&self, percentile: f64) -> Result<Bucket, Error>
Return the nearest value for the requested percentile (0.0 - 100.0)
across the total range of samples retained in the Heatmap.
Note: since the heatmap stores a distribution across a configured time span, sequential calls to fetch the percentile might result in different results even without concurrent writers. For instance, you may see a 90th percentile that is higher than the 100th percentile depending on the timing of calls to this function and the distribution of your data.
Note: concurrent writes may also effect the value returned by this function. Users needing better consistency should ensure that other threads are not writing into the heatmap while this function is in-progress.