Struct Bucket

pub struct Bucket {
    pub timestamp: UnixTimestamp,
    pub width: u64,
    pub name: MetricName,
    pub value: BucketValue,
    pub tags: MetricTags,
    pub metadata: BucketMetadata,
}

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:

• Counters store a single value, serialized as floating point.
• Distributions and sets store the full set of reported values.
• Gauges store a snapshot of reported values, see GaugeValue.

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: MetricTags

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

impl Bucket

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");

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);
}

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

Returns the value of the specified tag if it exists.

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

impl CardinalityItem for Bucket

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

Metric namespace of the item.

fn name(&self) -> &MetricName

Name of the item.

fn to_hash(&self) -> u32

Transforms this item into a consistent hash.

impl Clone for Bucket

fn clone(&self) -> Bucket

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Bucket

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

Formats the value using the given formatter.

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

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 Bucket> for BucketView<'a>

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

Converts to this type from the input type.

impl PartialEq for Bucket

fn eq(&self, other: &Bucket) -> 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 Bucket

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 Bucket