Enum BucketValue

pub enum BucketValue {
    Counter(CounterType),
    Distribution(DistributionValue),
    Set(SetValue),
    Gauge(GaugeValue),
}

The aggregated value of a metric bucket.

Variants

Counter(CounterType)

Counts instances of an event (MetricType::Counter).

Counters can be incremented and decremented. The default operation is to increment a counter by 1, although increments by larger values are equally possible.

Statsd Format

Counters are declared as "c". Alternatively, "m" is allowed.

There can be a variable number of floating point values. If more than one value is given, the values are summed into a single counter value:

endpoint.hits:4.5:21:17.0|c

Serialization

This variant serializes to a double precision float.

Aggregation

Counters aggregate by folding individual values into a single sum value per bucket. The sum is ingested and stored directly.

Distribution(DistributionValue)

Builds a statistical distribution over values reported (MetricType::Distribution).

Based on individual reported values, distributions allow to query the maximum, minimum, or average of the reported values, as well as statistical quantiles. With an increasing number of values in the distribution, its accuracy becomes approximate.

Statsd Format

Distributions are declared as "d". Alternatively, "d" and "ms" are allowed.

There can be a variable number of floating point values. These values are collected directly in a list per bucket.

endpoint.response_time@millisecond:36:49:57:68|d

Serialization

This variant serializes to a list of double precision floats, see DistributionValue.

Aggregation

During ingestion, all individual reported values are collected in a lossless format. In storage, these values are compressed into data sketches that allow to query quantiles. Separately, the count and sum of the reported values is stored, which makes distributions a strict superset of counters.

Set(SetValue)

Counts the number of unique reported values.

Sets allow sending arbitrary discrete values, including strings, and store the deduplicated count. With an increasing number of unique values in the set, its accuracy becomes approximate. It is not possible to query individual values from a set.

Statsd Format

Sets are declared as "s". Values in the list should be deduplicated.

endpoint.users:3182887624:4267882815|s
endpoint.users:e2546e4c-ecd0-43ad-ae27-87960e57a658|s

Serialization

This variant serializes to a list of 32-bit integers.

Aggregation

Set values are internally represented as 32-bit integer hashes of the original value. These hashes can be ingested directly as seen in the first example above. If raw strings are sent, they will be hashed on-the-fly.

Internally, set metrics are stored in data sketches that expose an approximate cardinality.

Gauge(GaugeValue)

Stores absolute snapshots of values.

In addition to plain counters, gauges store a snapshot of the maximum, minimum and sum of all values, as well as the last reported value. Note that the “last” component of this aggregation is not commutative. Which value is preserved as last value is implementation-defined.

Statsd Format

Gauges are declared as "g". There are two ways to ingest gauges:

1. As a single value. In this case, the provided value is assumed as the last, minimum, maximum, and the sum.
2. As a sequence of five values in the order: last, min, max, sum, count.

endpoint.parallel_requests:25|g
endpoint.parallel_requests:25:17:42:220:85|g

Serialization

This variant serializes to a structure with named fields, see GaugeValue.

Aggregation

Gauges aggregate by folding each of the components based on their semantics:

• last assumes the newly added value
• min retains the smaller value
• max retains the larger value
• sum adds the new value to the existing sum
• count adds the count of the newly added gauge (defaulting to 1)

Implementations

impl BucketValue

pub fn counter(value: CounterType) -> Self

Returns a bucket value representing a counter with the given value.

pub fn distribution(value: DistributionType) -> Self

Returns a bucket value representing a distribution with a single given value.

pub fn set(value: SetType) -> Self

Returns a bucket value representing a set with a single given hash value.

pub fn set_from_str(string: &str) -> Self

Returns a bucket value representing a set with a single given string value.

pub fn set_from_display(display: impl Display) -> Self

Returns a bucket value representing a set with a single given value.

pub fn gauge(value: GaugeType) -> Self

Returns a bucket value representing a gauge with a single given value.

pub fn ty(&self) -> MetricType

Returns the type of this value.

pub fn len(&self) -> usize

Returns the number of raw data points in this value.

pub fn is_empty(&self) -> bool

Returns true if this bucket contains no values.

pub fn cost(&self) -> usize

Estimates the number of bytes needed to encode the bucket value.

Note that this does not necessarily match the exact memory footprint of the value, because data structures have a memory overhead.

pub fn merge(&mut self, other: Self) -> Result<(), Self>

Merges the given bucket_value into self.

Returns Ok(()) if the two bucket values can be merged. This is the case when both bucket values are of the same variant. Otherwise, this returns Err(other).

Trait Implementations

impl Clone for BucketValue

fn clone(&self) -> BucketValue

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for BucketValue

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for BucketValue

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<'a> From<&'a BucketValue> for BucketViewValue<'a>

fn from(value: &'a BucketValue) -> Self

Converts to this type from the input type.

impl PartialEq for BucketValue

fn eq(&self, other: &BucketValue) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for BucketValue

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for BucketValue