Struct relay_metrics::Bucket

source ·
pub struct Bucket {
    pub timestamp: UnixTimestamp,
    pub width: u64,
    pub name: MetricName,
    pub value: BucketValue,
    pub tags: BTreeMap<String, String>,
    pub metadata: BucketMetadata,
}
Expand description

An aggregation of metric values.

As opposed to single metric values, bucket aggregations can carry multiple values. See MetricType for a description on how values are aggregated in buckets. Values are aggregated by metric name, type, time window, and all tags. Particularly, this allows metrics to have the same name even if their types differ.

See the crate documentation for general information on Metrics.

§Values

The contents of a bucket, especially their representation and serialization, depend on the metric type:

§Submission Protocol

<name>[@unit]:<value>[:<value>...]|<type>[|#<tag_key>:<tag_value>,<tag>][|T<timestamp>]

See the field documentation for more information on the components. An example submission looks like this:

endpoint.response_time@millisecond:36:49:57:68|d|#route:user_index|T1615889440
endpoint.hits:4|c|#route:user_index|T1615889440
endpoint.parallel_requests:25:17:42:220:85|g|#route:user_index|T1615889440
endpoint.users:3182887624:4267882815|s|#route:user_index|T1615889440

To parse a submission payload, use Bucket::parse_all.

§JSON Representation

Alternatively to the submission protocol, metrics can be represented as structured data in JSON. The data type of the value field is determined by the metric type.

In addition to the submission protocol, buckets have a required width field in their JSON representation.

[
  {
    "timestamp": 1615889440,
    "width": 0,
    "name": "d:custom/endpoint.response_time@millisecond",
    "type": "d",
    "value": [
      36.0,
      49.0,
      57.0,
      68.0
    ],
    "tags": {
      "route": "user_index"
    }
  },
  {
    "timestamp": 1615889440,
    "width": 0,
    "name": "c:custom/endpoint.hits@none",
    "type": "c",
    "value": 4.0,
    "tags": {
      "route": "user_index"
    }
  },
  {
    "timestamp": 1615889440,
    "width": 0,
    "name": "g:custom/endpoint.parallel_requests@none",
    "type": "g",
    "value": {
      "last": 25.0,
      "min": 17.0,
      "max": 42.0,
      "sum": 220.0,
      "count": 85
    },
    "tags": {
      "route": "user_index"
    }
  },
  {
    "timestamp": 1615889440,
    "width": 0,
    "name": "s:custom/endpoint.users@none",
    "type": "s",
    "value": [
      3182887624,
      4267882815
    ],
    "tags": {
      "route": "user_index"
    }
  }
]

To parse a JSON payload, use serde_json.

§Hashing of Sets

Set values can be specified as strings in the submission protocol. They are always hashed into a 32-bit value and the original value is dropped. If the submission protocol contains a 32-bit integer, it will be used directly, instead.

Example:

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

The above submission is represented as:

{
  "name": "s:custom/endpoint.users@none",
  "width": 0,
  "timestamp": 1615889449,
  "value": [4267882815],
  "type": "s"
}

Fields§

§timestamp: UnixTimestamp

The start time of the bucket’s time window.

If a timestamp is not supplied as part of the submission payload, the default timestamp supplied to Bucket::parse or Bucket::parse_all is associated with the metric. It is then aligned with the aggregation window.

§Statsd Format

In statsd, timestamps are part of the |-separated list following values. Timestamps start with the literal character 'T' followed by the UNIX timestamp.

The timestamp must be a positive integer in decimal notation representing the value of the UNIX timestamp.

§Example

endpoint.hits:1|c|T1615889440
§width: u64

The length of the time window in seconds.

To initialize a new bucket, choose 0 as width. Once the bucket is tracked by Relay’s aggregator, the width is aligned with configuration for the namespace and the timestamp is adjusted accordingly.

§Statsd Format

Specifying the bucket width in statsd is not supported.

§name: MetricName

The name of the metric in MRI (metric resource identifier) format.

MRIs have the format <type>:<ns>/<name>@<unit>. See MetricResourceIdentifier for information on fields and representations.

§Statsd Format

MRIs are sent in a more relaxed format: [<namespace/]name[@unit]. The value type is not part of the metric name and namespaces are optional.

Namespaces and units must consist of ASCII characters and match the regular expression /\w+/. The name component of MRIs consist of unicode characters and must match the regular expression /\w[\w\-.]*/. Note that the name must begin with a letter.

Per convention, dots separate metric names into components, where the leading components are considered namespaces and the final component is the name of the metric within its namespace.

§Examples

endpoint.hits:1|c
custom/endpoint.hits:1|c
custom/endpoint.duration@millisecond:21.5|d
§value: BucketValue

The type and aggregated values of this bucket.

Buckets support multiple values that are aggregated and can be accessed using a range of aggregation functions depending on the value type. While always a variable number of values can be sent in, some aggregations reduce the raw values to a fixed set of aggregates.

See BucketValue for more examples and semantics.

§Statsd Payload

The bucket value and its type are specified in separate fields following the metric name in the format: <name>:<value>|<type>. Values must be base-10 floating point numbers with optional decimal places.

It is possible to pack multiple values into a single datagram, but note that the type and the value representation must match for this. Refer to the BucketValue docs for more examples.

§Example

endpoint.hits:21|c
endpoint.hits:4.5|c
§tags: BTreeMap<String, String>

A list of tags adding dimensions to the metric for filtering and aggregation.

Tags allow to compute separate aggregates to filter or group metric values by any number of dimensions. Tags consist of a unique tag key and one associated value. For tags with missing values, an empty "" value is assumed at query time.

§Statsd Format

Tags are preceded with a hash # and specified in a comma (,) separated list. Each tag can either be a tag name, or a name:value combination. Tags are optional and can be omitted.

Tag keys are restricted to ASCII characters and must match the regular expression /[\w\-.\/]+/.

Tag values can contain unicode characters with the following escaping rules:

  • Tab is escaped as \t.
  • Carriage return is escaped as \r.
  • Line feed is escaped as \n.
  • Backslash is escaped as \\.
  • Commas and pipes are given unicode escapes in the form \u{2c} and \u{7c}, respectively.

§Example

endpoint.hits:1|c|#route:user_index,environment:production,release:1.4.0
§metadata: BucketMetadata

Relay internal metadata for a metric bucket.

The metadata contains meta information about the metric bucket itself, for example how many this bucket has been aggregated in total.

Implementations§

source§

impl Bucket

source

pub fn parse( slice: &[u8], timestamp: UnixTimestamp ) -> Result<Self, ParseMetricError>

Parses a single metric aggregate from the raw protocol.

See the Bucket for more information on the protocol.

§Example
use relay_metrics::{Bucket, UnixTimestamp};

let bucket = Bucket::parse(b"response_time@millisecond:57|d", UnixTimestamp::now())
    .expect("metric should parse");
source

pub fn parse_all(slice: &[u8], timestamp: UnixTimestamp) -> ParseBuckets<'_>

Parses a set of metric aggregates from the raw protocol.

Returns a metric result for each line in slice, ignoring empty lines. Both UNIX newlines (\n) and Windows newlines (\r\n) are supported.

It is possible to continue consuming the iterator after Err is yielded.

See Bucket for more information on the protocol.

§Example
use relay_metrics::{Bucket, UnixTimestamp};

let data = br#"
endpoint.response_time@millisecond:57|d
endpoint.hits:1|c
"#;

for metric_result in Bucket::parse_all(data, UnixTimestamp::now()) {
    let bucket = metric_result.expect("metric should parse");
    println!("Metric {}: {:?}", bucket.name, bucket.value);
}
source

pub fn tag(&self, name: &str) -> Option<&str>

Returns the value of the specified tag if it exists.

source

pub fn remove_tag(&mut self, name: &str) -> Option<String>

Removes the value of the specified tag.

If the tag exists, the removed value is returned.

Trait Implementations§

source§

impl CardinalityItem for Bucket

source§

fn namespace(&self) -> Option<MetricNamespace>

Metric namespace of the item. Read more
source§

fn name(&self) -> &MetricName

Name of the item.
source§

fn to_hash(&self) -> u32

Transforms this item into a consistent hash.
source§

impl Clone for Bucket

source§

fn clone(&self) -> Bucket

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Bucket

source§

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

Formats the value using the given formatter. Read more
source§

impl<'de> Deserialize<'de> for Bucket

source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
source§

impl<'a> From<&'a Bucket> for BucketView<'a>

source§

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

Converts to this type from the input type.
source§

impl PartialEq for Bucket

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl Serialize for Bucket

source§

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

Serialize this value into the given Serde serializer. Read more
source§

impl StructuralPartialEq for Bucket

Auto Trait Implementations§

§

impl Freeze for Bucket

§

impl RefUnwindSafe for Bucket

§

impl Send for Bucket

§

impl Sync for Bucket

§

impl Unpin for Bucket

§

impl UnwindSafe for Bucket

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> DynClone for T
where T: Clone,

source§

fn __clone_box(&self, _: Private) -> *mut ()

source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<V, T> VZip<V> for T
where V: MultiLane<T>,

§

fn vzip(self) -> V

source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,