Struct cadence::UnixMetricSink

pub struct UnixMetricSink { /* private fields */ }

Implementation of a MetricSink that emits metrics over a Unix socket.

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

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

Note that unlike the UDP sinks, if there is no receiving socket at the path specified or nothing listening at the path, an error will be returned when metrics are emitted.

Implementations

impl UnixMetricSink

pub fn from<P>(path: P, socket: UnixDatagram) -> UnixMetricSinkwhere P: AsRef<Path>,

Construct a new UnixMetricSink instance.

The socket does not need to be bound (i.e. UnixDatagram::unbound() is fine) but should have any desired configuration already applied (blocking vs non-blocking, timeouts, etc.).

Example

use std::os::unix::net::UnixDatagram;
use cadence::UnixMetricSink;

let socket = UnixDatagram::unbound().unwrap();
let sink = UnixMetricSink::from("/run/statsd.sock", socket);

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

Non-blocking Example

use std::os::unix::net::UnixDatagram;
use cadence::UnixMetricSink;

let socket = UnixDatagram::unbound().unwrap();
socket.set_nonblocking(true).unwrap();
let sink = UnixMetricSink::from("/run/statsd.sock", socket);

Examples found in repository

examples/unix-socket.rs (line 32)

fn main() {
    let harness = UnixServerHarness::new("unix-socket-example");
    harness.run(
        |s: String| println!("Got {} bytes from socket: {}", s.len(), s),
        |path| {
            let socket = UnixDatagram::unbound().unwrap();
            let sink = UnixMetricSink::from(path, socket);
            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 UnixMetricSink

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

Formats the value using the given formatter.

impl MetricSink for UnixMetricSink

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.