Struct sentry_core::metrics::Metric

pub struct Metric { /* private fields */ }

A metric value that contains a numeric value and metadata to be sent to Sentry.

Units

To make the most out of metrics in Sentry, consider assigning a unit during construction. This can be achieved using the with_unit builder method. See the documentation for more examples on units.

use sentry::metrics::{Metric, InformationUnit};

Metric::distribution("request.size", 47.2)
    .with_unit(InformationUnit::Byte)
    .send();

Sending Metrics

Metrics can be sent to Sentry directly using the send method on the constructor. This will send the metric to the Client on the current Hub. If there is no client on the current hub, the metric is dropped.

use sentry::metrics::Metric;

Metric::count("requests")
    .with_tag("method", "GET")
    .send();

Sending to a Custom Client

Metrics can also be sent to a custom client. This is useful if you want to send metrics to a different Sentry project or with different configuration. To do so, finish building the metric and then call add_metric to the client:

use sentry::Hub;
use sentry::metrics::Metric;

let metric = Metric::count("requests")
   .with_tag("method", "GET")
   .finish();

// Obtain a client from somewhere
if let Some(client) = Hub::current().client() {
    client.add_metric(metric);
}

Implementations

impl Metric

pub fn build(name: impl Into<MetricStr>, value: MetricValue) -> MetricBuilder

Creates a new metric with the stated name and value.

The provided name identifies the metric in Sentry. It should consist of alphanumeric characters and _, -, and .. While a single forward slash (/) is also allowed in metric names, it has a special meaning and should not be used in regular metric names. All characters that do not match this criteria are sanitized.

The value of the metric determines its type. See the struct-level docs and constructor methods for examples on how to build metrics.

pub fn parse_statsd(string: &str) -> Result<Self, ParseMetricError>

Parses a metric from a StatsD string.

This supports regular StatsD payloads with an extension for tags. In the below example, tags are optional:

<metricname>:<value>|<type>|#<tag1>:<value1>,<tag2>:<value2>

Units are encoded into the metric name, separated by an @:

<metricname>@<unit>:<value>|<type>|#<tag1>:<value1>,<tag2>:<value2>

pub fn incr(name: impl Into<MetricStr>, value: f64) -> MetricBuilder

Builds a metric that increments a counter by the given value.

Example

use sentry::metrics::{Metric};

Metric::incr("operation.total_values", 7.0).send();

pub fn count(name: impl Into<MetricStr>) -> MetricBuilder

Builds a metric that counts the single occurrence of an event.

Example

use sentry::metrics::{Metric};

Metric::count("requests").send();

pub fn timing(name: impl Into<MetricStr>, timing: Duration) -> MetricBuilder

Builds a metric that tracks the duration of an operation.

This is a distribution metric that is tracked in seconds.

Example

use std::time::Duration;
use sentry::metrics::{Metric};

Metric::timing("operation", Duration::from_secs(1)).send();

pub fn distribution(name: impl Into<MetricStr>, value: f64) -> MetricBuilder

Builds a metric that tracks the distribution of values.

Example

use sentry::metrics::{Metric};

Metric::distribution("operation.batch_size", 42.0).send();

pub fn set(name: impl Into<MetricStr>, string: &str) -> MetricBuilder

Builds a metric that tracks the unique number of values provided.

See MetricValue for more ways to construct sets.

Example

use sentry::metrics::{Metric};

Metric::set("users", "user1").send();

pub fn gauge(name: impl Into<MetricStr>, value: f64) -> MetricBuilder

Builds a metric that tracks the snapshot of provided values.

Example

use sentry::metrics::{Metric};

Metric::gauge("cache.size", 42.0).send();

pub fn send(self)

Sends the metric to the current client.

When building a metric, you can use MetricBuilder::send to send the metric directly. If there is no client on the current Hub, the metric is dropped.

pub fn to_envelope(self) -> Envelope

Convert the metric into an Envelope containing a single EnvelopeItem::Statsd.

Trait Implementations

impl Debug for Metric

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

Formats the value using the given formatter.