Crate relay_statsd

A high-level StatsD metric client built on cadence.

Defining Metrics

In order to use metrics, one needs to first define one of the metric traits on a custom enum. The following types of metrics are available: counter, timer, gauge, histogram, and set. For explanations on what that means see Metric Types.

The metric traits serve only to provide a type safe metric name. All metric types have exactly the same form, they are different only to ensure that a metric can only be used for the type for which it was defined, (e.g. a counter metric cannot be used as a timer metric). See the traits for more detailed examples.

Initializing the Client

Metrics can be used without initializing a statsd client. In that case, invoking with_client or the metric! macro will become a noop. Only when configured, metrics will actually be collected.

To initialize the client, either use set_client to pass a custom client, or use init to create a default client with known arguments:

relay_statsd::init("myprefix", "localhost:8125", BTreeMap::new(), 1.0, true);

Macro Usage

The recommended way to record metrics is by using the metric! macro. See the trait docs for more information on how to record each type of metric.

use relay_statsd::{metric, CounterMetric};

struct MyCounter;

impl CounterMetric for MyCounter {
    fn name(&self) -> &'static str {
        "counter"
    }
}

metric!(counter(MyCounter) += 1);

Manual Usage

use relay_statsd::prelude::*;

relay_statsd::with_client(|client| {
    client.count("mymetric", 1).ok();
});

Modules

prelude

The metrics prelude that is necessary to use the client.

Macros

metric

Emits a metric.

Structs

MetricsClient

Client configuration object to store globally.

Traits

CounterMetric

A metric for capturing counters.

GaugeMetric

A metric for capturing gauges.

HistogramMetric

A metric for capturing histograms.

SetMetric

A metric for capturing sets.

TimerMetric

A metric for capturing timings.

Functions

disable

Disable the client again.

init

Tell the metrics system to report to statsd.

init_basic

set_client

Set a new statsd client.

with_capturing_test_client

Set a test client for the period of the called function (only affects the current thread).

with_client

Invoke a callback with the current statsd client.