Struct cadence::StatsdClient

pub struct StatsdClient { /* private fields */ }

Client for Statsd that implements various traits to record metrics.

Traits

The client is the main entry point for users of this library. It supports several traits for recording metrics of different types.

• Counted for emitting counters.
• Timed for emitting timings.
• Gauged for emitting gauge values.
• Metered for emitting meter values.
• Histogrammed for emitting histogram values.
• Setted for emitting set values.
• MetricClient for a combination of all of the above.

For more information about the uses for each type of metric, see the documentation for each mentioned trait.

Sinks

The client uses some implementation of a MetricSink to emit the metrics.

In simple use cases when performance isn’t critical, the UdpMetricSink is an acceptable choice since it is the simplest to use and understand.

When performance is more important, users will want to use the BufferedUdpMetricSink in combination with the QueuingMetricSink for maximum isolation between the sending of metrics and your application as well as minimum overhead when sending metrics.

Threading

The StatsdClient is designed to work in a multithreaded application. All parts of the client can be shared between threads (i.e. it is Send and Sync). Some common ways to use the client in a multithreaded environment are given below.

In each of these examples, we create a struct MyRequestHandler that has a single method that spawns a thread to do some work and emit a metric.

Wrapping With An Arc

One option is to put all accesses to the client behind an atomic reference counting pointer (std::sync::Arc). If you are doing this, it makes sense to just refer to the client by the trait of all its methods for recording metrics (MetricClient) as well as the Send and Sync traits since the idea is to share this between threads.

use std::panic::RefUnwindSafe;
use std::net::UdpSocket;
use std::sync::Arc;
use std::thread;
use cadence::prelude::*;
use cadence::{StatsdClient, BufferedUdpMetricSink, DEFAULT_PORT};

struct MyRequestHandler {
    metrics: Arc<MetricClient + Send + Sync + RefUnwindSafe>,
}

impl MyRequestHandler {
    fn new() -> MyRequestHandler {
        let socket = UdpSocket::bind("0.0.0.0:0").unwrap();
        let host = ("localhost", DEFAULT_PORT);
        let sink = BufferedUdpMetricSink::from(host, socket).unwrap();
        MyRequestHandler {
            metrics: Arc::new(StatsdClient::from_sink("some.prefix", sink))
        }
    }

    fn handle_some_request(&self) -> Result<(), String> {
        let metric_ref = self.metrics.clone();
        let _t = thread::spawn(move || {
            println!("Hello from the thread!");
            metric_ref.incr("request.handler");
        });

        Ok(())
    }
}

Clone Per Thread

Another option for sharing the client between threads is just to clone client itself. Clones of the client are relatively cheap, typically only requiring a single heap allocation (of a String). While this cost isn’t nothing, it’s not too bad. An example of this is given below.

use std::net::UdpSocket;
use std::thread;
use cadence::prelude::*;
use cadence::{StatsdClient, BufferedUdpMetricSink, DEFAULT_PORT};

struct MyRequestHandler {
    metrics: StatsdClient,
}

impl MyRequestHandler {
    fn new() -> MyRequestHandler {
        let socket = UdpSocket::bind("0.0.0.0:0").unwrap();
        let host = ("localhost", DEFAULT_PORT);
        let sink = BufferedUdpMetricSink::from(host, socket).unwrap();
        MyRequestHandler {
            metrics: StatsdClient::from_sink("some.prefix", sink)
        }
    }

    fn handle_some_request(&self) -> Result<(), String> {
        let metric_clone = self.metrics.clone();
        let _t = thread::spawn(move || {
            println!("Hello from the thread!");
            metric_clone.incr("request.handler");
        });

        Ok(())
    }
}

As you can see, cloning the client itself looks a lot like using it with an Arc.

Implementations

impl StatsdClient

pub fn from_sink<T>(prefix: &str, sink: T) -> Selfwhere
    T: MetricSink + Sync + Send + RefUnwindSafe + 'static,

Create a new client instance that will use the given prefix for all metrics emitted to the given MetricSink implementation.

Note that this client will discard errors encountered when sending metrics via the MetricBuilder::send() method.

No-op Example

use cadence::{StatsdClient, NopMetricSink};

let prefix = "my.stats";
let client = StatsdClient::from_sink(prefix, NopMetricSink);

UDP Socket Example

use std::net::UdpSocket;
use cadence::{StatsdClient, UdpMetricSink, DEFAULT_PORT};

let prefix = "my.stats";
let host = ("127.0.0.1", DEFAULT_PORT);

let socket = UdpSocket::bind("0.0.0.0:0").unwrap();
socket.set_nonblocking(true).unwrap();

let sink = UdpMetricSink::from(host, socket).unwrap();
let client = StatsdClient::from_sink(prefix, sink);

Buffered UDP Socket Example

use std::net::UdpSocket;
use cadence::{StatsdClient, BufferedUdpMetricSink, DEFAULT_PORT};

let prefix = "my.stats";
let host = ("127.0.0.1", DEFAULT_PORT);

let socket = UdpSocket::bind("0.0.0.0:0").unwrap();

let sink = BufferedUdpMetricSink::from(host, socket).unwrap();
let client = StatsdClient::from_sink(prefix, sink);

pub fn from_udp_host<A>(prefix: &str, host: A) -> MetricResult<Self>where
    A: ToSocketAddrs,

Create a new client instance that will use the given prefix to send metrics to the given host over UDP using an appropriate sink.

The created UDP socket will be put into non-blocking mode.

Note that this client will discard errors encountered when sending metrics via the MetricBuilder::send() method.

Example

use cadence::{StatsdClient, UdpMetricSink};

let prefix = "my.stats";
let host = ("metrics.example.com", 8125);

let client = StatsdClient::from_udp_host(prefix, host);

Failures

This method may fail if:

• It is unable to create a local UDP socket.
• It is unable to put the UDP socket into non-blocking mode.
• It is unable to resolve the hostname of the metric server.
• The host address is otherwise unable to be parsed.

pub fn builder<T>(prefix: &str, sink: T) -> StatsdClientBuilderwhere
    T: MetricSink + Sync + Send + RefUnwindSafe + 'static,

Create a new builder with the provided prefix and metric sink.

A prefix and a metric sink are required to create a new client instance. All other optional customizations can be set by calling methods on the returned builder. Any customizations that aren’t set by the caller will use defaults.

General defaults:

• A no-op error handler will be used by default. Note that this only affects errors encountered when using the MetricBuilder::send() method (as opposed to .try_send() or any other method for sending metrics).

Example

use cadence::prelude::*;
use cadence::{StatsdClient, MetricError, NopMetricSink};

fn my_handler(err: MetricError) {
    println!("Metric error: {}", err);
}

let client = StatsdClient::builder("some.prefix", NopMetricSink)
    .with_error_handler(my_handler)
    .build();

client.gauge_with_tags("some.key", 7)
   .with_tag("region", "us-west-1")
   .send();

Trait Implementations

impl Clone for StatsdClient

fn clone(&self) -> StatsdClient

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Counted for StatsdClient

fn count_with_tags<'a>(
    &'a self,
    key: &'a str,
    count: i64
) -> MetricBuilder<'_, '_, Counter>

Increment or decrement the counter by the given amount and return a MetricBuilder that can be used to add tags to the metric.

fn incr(&self, key: &str) -> MetricResult<Counter>

Increment the counter by 1

fn incr_with_tags<'a>(&'a self, key: &'a str) -> MetricBuilder<'_, '_, Counter>

Increment the counter by 1 and return a MetricBuilder that can be used to add tags to the metric.

fn decr(&self, key: &str) -> MetricResult<Counter>

Decrement the counter by 1

fn decr_with_tags<'a>(&'a self, key: &'a str) -> MetricBuilder<'_, '_, Counter>

Decrement the counter by 1 and return a `MetricBuilder that can be used to add tags to the metric.

fn count(&self, key: &str, count: i64) -> MetricResult<Counter>

Increment or decrement the counter by the given amount

impl Debug for StatsdClient

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

Formats the value using the given formatter.

impl Gauged for StatsdClient

fn gauge_with_tags<'a>(
    &'a self,
    key: &'a str,
    value: u64
) -> MetricBuilder<'_, '_, Gauge>

Record a gauge value with the given key and return a MetricBuilder that can be used to add tags to the metric.

fn gauge(&self, key: &str, value: u64) -> MetricResult<Gauge>

Record a gauge value with the given key

impl Histogrammed for StatsdClient

fn histogram_with_tags<'a>(
    &'a self,
    key: &'a str,
    value: u64
) -> MetricBuilder<'_, '_, Histogram>

Record a single histogram value with the given key and return a MetricBuilder that can be used to add tags to the metric.

fn histogram(&self, key: &str, value: u64) -> MetricResult<Histogram>

Record a single histogram value with the given key

impl Metered for StatsdClient

fn meter_with_tags<'a>(
    &'a self,
    key: &'a str,
    value: u64
) -> MetricBuilder<'_, '_, Meter>

Record a meter value with the given key and return a MetricBuilder that can be used to add tags to the metric.

fn mark(&self, key: &str) -> MetricResult<Meter>

Record a single metered event with the given key

fn mark_with_tags<'a>(&'a self, key: &'a str) -> MetricBuilder<'_, '_, Meter>

Record a single metered event with the given key and return a MetricBuilder that can be used to add tags to the metric.

fn meter(&self, key: &str, value: u64) -> MetricResult<Meter>

Record a meter value with the given key

impl MetricBackend for StatsdClient

fn send_metric<M>(&self, metric: &M) -> MetricResult<()>where
    M: Metric,

Send a full formed Metric implementation via the underlying MetricSink

fn consume_error(&self, err: MetricError)

Consume a possible error from attempting to send a metric.

impl Setted for StatsdClient

fn set_with_tags<'a>(
    &'a self,
    key: &'a str,
    value: i64
) -> MetricBuilder<'_, '_, Set>

Record a single set value with the given key and return a MetricBuilder that can be used to add tags to the metric.

fn set(&self, key: &str, value: i64) -> MetricResult<Set>

Record a single set value with the given key

impl Timed for StatsdClient

fn time_with_tags<'a>(
    &'a self,
    key: &'a str,
    time: u64
) -> MetricBuilder<'_, '_, Timer>

Record a timing in milliseconds with the given key and return a MetricBuilder that can be used to add tags to the metric.

fn time_duration_with_tags<'a>(
    &'a self,
    key: &'a str,
    duration: Duration
) -> MetricBuilder<'_, '_, Timer>

Record a timing in milliseconds with the given key and return a MetricBuilder that can be used to add tags to the metric.

fn time(&self, key: &str, time: u64) -> MetricResult<Timer>

Record a timing in milliseconds with the given key

fn time_duration(&self, key: &str, duration: Duration) -> MetricResult<Timer>

Record a timing in milliseconds with the given key

impl MetricClient for StatsdClient