Crate relay_metrics

Expand description

Metric protocol, aggregation and processing for Sentry.

Metrics are high-volume values sent from Sentry clients, integrations, or extracted from errors and transactions, that can be aggregated and queried over large time windows. As opposed to rich errors and transactions, metrics carry relatively little context information in tags with low cardinality.

§Protocol

Clients submit metrics in a text-based protocol based on StatsD. See the field documentation on Bucket for more information on the components. A sample 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

The metric type is part of its signature just like the unit. Therefore, it is allowed to reuse a metric name for multiple metric types, which will result in multiple metrics being recorded.

§Metric Envelopes

To send one or more metrics to Relay, the raw protocol is enclosed in an envelope item of type metrics:

{}
{"type": "statsd", ...}
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
...

Note that the name format used in the statsd protocol is different from the MRI: Metric names are not prefixed with <ty>: as the type is somewhere else in the protocol. If no metric namespace is specified, the "custom" namespace is assumed.

Optionally, a timestamp can be added to every line of the submitted envelope. The timestamp has to be a valid Unix timestamp (UTC) and must be prefixed with T. If it is omitted, the received time of the envelope is assumed.

§Aggregation

Relay accumulates all metrics in time buckets before sending them onwards. Aggregation is handled by the aggregator::Aggregator, which should be created once for the entire system. It flushes aggregates in regular intervals, either shortly after their original time window has passed or with a debounce delay for backdated submissions.

Warning: With chained Relays submission delays accumulate.

Aggregate buckets are encoded in JSON with the following schema:

[
  {
    "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"
    }
  }
]

§Ingestion

Processing Relays write aggregate buckets into the ingestion Kafka stream. The schema is similar to the aggregation payload, with the addition of scoping information. Each bucket is sent in a separate message:

{
  "org_id": 1,
  "project_id": 42,
  "name": "endpoint.response_time",
  "unit": "millisecond",
  "value": [
    36.0,
    49.0,
    57.0,
    68.0
  ],
  "type": "d",
  "timestamp": 1615889440,
  "tags": {
    "route": "user_index"
  }
}

Modules§

aggregator: Core functionality of metrics aggregation.
cogs: COGS related metric utilities.

Macros§

dist: Creates a DistributionValue containing the given arguments.

Structs§

Bucket: An aggregation of metric values.
BucketMetadata: Relay internal metadata for a metric bucket.
BucketView: A view into a metrics bucket. Sometimes also called a partial bucket. A view contains a subset of datapoints of the original bucket.
BucketsView: A view into a slice of metric buckets.
BucketsViewBySizeIter: Iterator slicing a BucketsView into smaller views constrained by a given size in bytes.
BucketsViewIter: Iterator yielding all items contained in a BucketsView.
ByNamespace: Utility to store information for each MetricNamespace.
CustomUnit: Custom user-defined units without builtin conversion.
FiniteF64: A finite 64-bit floating point type.
GaugeValue: A snapshot of values within a Bucket.
MetricName: Optimized string represenation of a metric name.
MetricResourceIdentifier: A unique identifier for metrics including typing and namespacing.
ParseBuckets: Iterator over parsed metrics returned from Bucket::parse_all.
ParseFiniteFloatError: Error type returned when parsing FiniteF64 fails.
ParseMetricError: An error returned when metrics or MRIs cannot be parsed.
ParseMetricUnitError: An error parsing a MetricUnit or one of its variants.
SetView: A view into the datapoints of a set metric.
TryFromFloatError: Error type returned when conversion to FiniteF64 fails.
UnixTimestamp: A unix timestamp (full seconds elapsed since 1970-01-01 00:00 UTC).

Enums§

BucketValue: The aggregated value of a metric bucket.
BucketViewValue: A view into the datapoints of a BucketValue.
DurationUnit: Time duration units used in MetricUnit::Duration.
FractionUnit: Units of fraction used in MetricUnit::Fraction.
InformationUnit: Size of information derived from bytes, used in MetricUnit::Information.
MetricNamespace: The namespace of a metric.
MetricType: The type of a MetricResourceIdentifier, determining its aggregation and evaluation.
MetricUnit: The unit of measurement of a metric value.
NormalizationError: Error returned from normalize_bucket.
UnescapeError: Unescaper’s Error.

Functions§

normalize_bucket: Normalizes a bucket.

Type Aliases§

CounterType: Type used for Counter metric
DistributionType: Type of distribution entries
DistributionValue: A distribution of values within a Bucket.
GaugeType: Type used for Gauge entries
MetricTags: Type of Bucket::tags.
SetType: Type used for set elements in Set metric
SetValue: A set of unique values.

Crate relay_metricsCopy item path