Struct cadence::QueuingMetricSink

pub struct QueuingMetricSink { /* private fields */ }

Implementation of a MetricSink that wraps another implementation and uses it to emit metrics asynchronously, in another thread.

Metrics submitted to this sink are queued and sent to the wrapped sink that is running in a separate thread. The wrapped implementation can be any thread (Sync + Send) and panic (RefUnwindSafe) safe MetricSink. Results from thew rapped implementation will be discarded.

The thread used for network operations (actually sending the metrics using the wrapped sink) is created and started when the QueuingMetricSink is created. The dequeuing of metrics is stopped and the thread stopped when QueuingMetricSink instance is destroyed (when .drop() is called).

Entries already queued are guaranteed to be sent to the wrapped sink before the queuing sink is stopped. Meaning, the following code ends up calling wrapped.emit(metric) on every metric submitted to the queuing sink.

Example

use cadence::{MetricSink, QueuingMetricSink, NopMetricSink};

let wrapped = NopMetricSink;
{
    let queuing = QueuingMetricSink::from(wrapped);
    queuing.emit("foo.counter:4|c");
    queuing.emit("bar.counter:5|c");
    queuing.emit("baz.gauge:6|g");
}

At the end of this code block, all metrics are guaranteed to be sent to the underlying wrapped metric sink before the thread used by the queuing sink is stopped.

Implementations

impl QueuingMetricSink

pub fn from<T>(sink: T) -> QueuingMetricSinkwhere
    T: MetricSink + Sync + Send + RefUnwindSafe + 'static,

Construct a new QueuingMetricSink instance wrapping another sink implementation.

The .emit() method of the wrapped sink will be executed in a different thread after being passed to it via a queue. The wrapped sink should be thread safe (Send + Sync) and panic safe (RefUnwindSafe).

The thread in which the wrapped sink runs is created when the QueuingMetricSink is created and stopped when the queuing sink is destroyed.

Buffered UDP Sink Example

In this example we wrap a buffered UDP sink to execute it in a different thread.

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

let socket = UdpSocket::bind("0.0.0.0:0").unwrap();
let host = ("metrics.example.com", DEFAULT_PORT);
let udp_sink = BufferedUdpMetricSink::from(host, socket).unwrap();
let queuing_sink = QueuingMetricSink::from(udp_sink);

pub fn panics(&self) -> usize

Return the number of times the wrapped sink or underlying worker thread has panicked and needed to be restarted. In typical use this should always be 0 but sometimes bugs happen.

Trait Implementations

impl Clone for QueuingMetricSink

fn clone(&self) -> QueuingMetricSink

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for QueuingMetricSink

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

Formats the value using the given formatter.

impl Drop for QueuingMetricSink

fn drop(&mut self)

Send the worker a signal to stop processing metrics.

Note that this destructor only sends the worker thread a signal to stop, it doesn’t wait for it to stop.

impl MetricSink for QueuingMetricSink

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.