Struct cadence::UdpMetricSink

pub struct UdpMetricSink { /* private fields */ }

Implementation of a MetricSink that emits metrics over UDP.

This is the most basic version of MetricSink that sends metrics over UDP. It accepts a UDP socket instance over which to write metrics and the address of the Statsd server to send packets to.

Each metric is sent to the Statsd server when the .emit() method is called, in the thread of the caller.

Implementations

impl UdpMetricSink

pub fn from<A>(to_addr: A, socket: UdpSocket) -> MetricResult<UdpMetricSink>where A: ToSocketAddrs,

Construct a new UdpMetricSink instance.

The address should be the address of the remote metric server to emit metrics to over UDP. The socket should already be bound to a local address with any desired configuration applied (blocking vs non-blocking, timeouts, etc.).

Example

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

let socket = UdpSocket::bind("0.0.0.0:0").unwrap();
let host = ("metrics.example.com", DEFAULT_PORT);
let sink = UdpMetricSink::from(host, socket);

To send metrics over a non-blocking socket, simply put the socket in non-blocking mode before creating the UDP metric sink.

Non-blocking Example

Note that putting the UDP socket into non-blocking mode is the default when sink and socket are automatically created with the StatsdClient::from_udp_host method.

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

let socket = UdpSocket::bind("0.0.0.0:0").unwrap();
socket.set_nonblocking(true).unwrap();
let host = ("metrics.example.com", DEFAULT_PORT);
let sink = UdpMetricSink::from(host, socket);

Failures

This method may fail if:

• It is unable to resolve the hostname of the metric server.
• The host address is otherwise unable to be parsed

Examples found in repository

examples/simple-sink.rs (line 21)

fn main() {
    let sock = UdpSocket::bind("0.0.0.0:0").unwrap();
    let sink = UdpMetricSink::from(("localhost", DEFAULT_PORT), sock).unwrap();
    let metrics = StatsdClient::from_sink("example.prefix", sink);

    metrics.count("example.counter", 1).unwrap();
    metrics.gauge("example.gauge", 5).unwrap();
    metrics.gauge("example.gauge", 5.0).unwrap();
    metrics.time("example.timer", 32).unwrap();
    metrics.time("example.timer", Duration::from_millis(32)).unwrap();
    metrics.histogram("example.histogram", 22).unwrap();
    metrics
        .histogram("example.histogram", Duration::from_nanos(22))
        .unwrap();
    metrics.histogram("example.histogram", 22.0).unwrap();
    metrics.distribution("example.distribution", 33).unwrap();
    metrics.distribution("example.distribution", 33.0).unwrap();
    metrics.meter("example.meter", 8).unwrap();
    metrics.set("example.set", 44).unwrap();
}

Trait Implementations

impl Debug for UdpMetricSink

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

Formats the value using the given formatter.

impl MetricSink for UdpMetricSink

fn emit(&self, metric: &str) -> Result<usize>

Send the Statsd metric using this sink and return the number of bytes written or an I/O error.

fn flush(&self) -> Result<()>

Flush any currently buffered metrics to the underlying backend, returning an I/O error if they could not be written for some reason.