[−][src]Struct metrics_util::Summary
A quantile sketch with relative-error guarantees.
Based on DDSketch, Summary
provides quantiles over an arbitrary distribution of
floating-point numbers, including for negative numbers, using a space-efficient sketch that
provides relative-error guarantees, regardless of the absolute range between the smallest and
larger values.
Summary
is similiar to HDRHistogram in practice, but supports an arbitrary
range of values, and supports floating-point numbers.
Numbers with an absolute value smaller than given min_value
will be recognized as zeroes.
Memory usage for Summary
should be nearly identical to DDSketch
.
Summary::estimated_size
provides a rough estimate of summary size based on the current
values that have been added to it.
As mentioned above, this sketch provides relative-error guarantees across quantiles falling within 0 <= q <= 1, but trades some accuracy at the lowest quantiles as part of the collapsing scheme that allows for automatically handling arbitrary ranges of values, even when the maximum number of bins has been allocated. Typically, q=0.05 and below is where this error will be noticed, if present.
For cases when all values are positive, you can simply use Summary::min
in lieu of checking
these quantiles, as the minimum value will be closer to the true value. For cases when values
range from negative to positive, the aforementioned collapsing will perturb the estimated true
value for quantiles that conceptually fall within this collapsed band.
For example, for a distribution that spans from -25 to 75, we would intuitively expect q=0 to be -25, q=0.25 to be 0, q=0.5 to be 25, and so on. Internally, negative numbers and positive numbers are handled in two separate containers. Based on this example, one container would handle -25 to 0, and another would handle the 0 to 75 range. As the containers are mapped "back to back", q=0.25 for this hypothetical summary would actually be q=0 within the negative container, which may return an estimated true value that exceeds the relative error guarantees.
Of course, as these problems are related to the estimation aspect of this data structure, users can allow the summary to allocate more bins to compensate for these edge cases, if desired.
Implementations
impl Summary
[src]
pub fn new(alpha: f64, max_buckets: u32, min_value: f64) -> Summary
[src]
Creates a new Summary
.
alpha
represents the desired relative error for this summary. If alpha
was 0.0001, that
would represent a desired relative error of 0.01%. For example, if the true value at
quantile q0 was 1, the estimated value at that quantile would be a value within 0.01% of the
true value, or a value between 0.9999 and 1.0001.
max_buckets
controls how many subbuckets are created, which directly influences memory usage.
Each bucket "costs" eight bytes, so a summary with 2048 buckets would consume a maximum of
around 16 KiB. Depending on how many samples have been added to the summary, the number of
subbuckets allocated may be far below max_buckets
, and the summary will allocate more as
needed to fulfill the relative error guarantee.
min_value
controls the smallest value that will be recognized distinctly from zero. Said
another way, any value between -min_value
and min_value
will be counted as zero.
pub fn with_defaults() -> Summary
[src]
Creates a new Summary
with default values.
alpha
is 0.0001, max_buckets
is 32,768, and min_value
is 1.0e-9.
This will yield a summary that is roughly equivalent in memory usage to an HDRHistogram with 3 significant digits, and will support values down to a single nanosecond.
In practice, when using only positive values, maximum memory usage can be expected to hover around 200KiB, while usage of negative values can lead to an average maximum size of around 400KiB.
pub fn add(&mut self, value: f64)
[src]
Adds a sample to the summary.
If the absolute value of value
is smaller than given min_value
, it will be added as a zero.
pub fn quantile(&self, q: f64) -> Option<f64>
[src]
Gets the estimated value at the given quantile.
If the sketch is empty, or if the quantile is less than 0.0 or greater than 1.0, then the
result will be None
.
While q
can be either 0.0 or 1.0, callers should prefer to use Summary::min
and
Summary::max
as the values will be the true values, and not an estimation.
pub fn min(&self) -> f64
[src]
Gets the minimum value this summary has seen so far.
pub fn max(&self) -> f64
[src]
Gets the maximum value this summary has seen so far.
pub fn is_empty(&self) -> bool
[src]
Whether or not this summary is empty.
pub fn count(&self) -> usize
[src]
Gets the number of samples in this summary.
pub fn detailed_count(&self) -> (usize, usize, usize)
[src]
Gets the number of samples in this summary by zeroes, negative, and positive counts.
pub fn estimated_size(&self) -> usize
[src]
Gets the estimized size of this summary, in bytes.
In practice, this value should be very close to the actual size, but will not be entirely precise.
Trait Implementations
Auto Trait Implementations
impl RefUnwindSafe for Summary
[src]
impl Send for Summary
[src]
impl Sync for Summary
[src]
impl Unpin for Summary
[src]
impl UnwindSafe for Summary
[src]
Blanket Implementations
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
pub fn borrow_mut(&mut self) -> &mut T
[src]
impl<T> From<T> for T
[src]
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
impl<T> Pointable for T
[src]
pub const ALIGN: usize
[src]
type Init = T
The type for initializers.
pub unsafe fn init(init: <T as Pointable>::Init) -> usize
[src]
pub unsafe fn deref<'a>(ptr: usize) -> &'a T
[src]
pub unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T
[src]
pub unsafe fn drop(ptr: usize)
[src]
impl<T> ToOwned for T where
T: Clone,
[src]
T: Clone,
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
[src]
pub fn clone_into(&self, target: &mut T)
[src]
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
[src]
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,