Struct cadence::StatsdClient

pub struct StatsdClient<T: MetricSink> { /* fields omitted */ }

Client for Statsd that implements various traits to record metrics.

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.
• 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.

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

In simple use cases when performance isn't critical, the UdpMetricSink is likely the best 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 AsyncMetricSink for maximum isolation between the sending metrics and your application as well as minimum overhead when sending metrics.

Methods

impl<T: MetricSink> StatsdClient<T>

fn from_sink(prefix: &str, sink: T) -> StatsdClient<T>

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

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

fn from_udp_host<A>(prefix: &str,
                    host: A)
                    -> MetricResult<StatsdClient<UdpMetricSink>> 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 you must include a type parameter when you call this method to help the compiler determine the type of T (the sink).

Example

use cadence::{StatsdClient, UdpMetricSink};

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

// Note that we include a type parameter for the method call
let client = StatsdClient::<UdpMetricSink>::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.

Trait Implementations

impl<T: Debug + MetricSink> Debug for StatsdClient<T>

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<T: Clone + MetricSink> Clone for StatsdClient<T>

fn clone(&self) -> StatsdClient<T>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: MetricSink> Counted for StatsdClient<T>

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

Increment the counter by 1

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

Decrement the counter by 1

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

Increment or decrement the counter by the given amount

impl<T: MetricSink> Timed for StatsdClient<T>

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

Record a timing in milliseconds with the given key

impl<T: MetricSink> Gauged for StatsdClient<T>

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

Record a gauge value with the given key

impl<T: MetricSink> Metered for StatsdClient<T>

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

Record a single metered event with the given key

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

Record a meter value with the given key

impl<T: MetricSink> Histogrammed for StatsdClient<T>

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

Record a single histogram value with the given key

impl<T: MetricSink> MetricClient for StatsdClient<T>