Metric Sinks for Cadence built on Tokio

A collection of Cadence Metric Sink implementations that process metrics asynchronously using Tokio.

The Statsd client provided by Cadence does not support asynchronous operation -- submitting a metric may in fact block the caller!

This is undesirable in asynchronous contexts.

The Metric Sinks implemented in this crate alleviate this issue by allowing the application code to enqueue metrics without blocking, and offloading their actual sending to a separate asynchronous task.

Features

• emit metrics without blocking by utilizing a non-blocking, buffered channel
• batch multiple metrics, up to a maximum delay (or when the batch buffer fills up)
• process metrics asynchronously in a Tokio task pool of the application's choice

Installation

Add cadence, tokio, and tokio-cadence to your Cargo.toml:

[dependencies]
cadence = "1"
tokio = { version = "1", features = ["full"] }
tokio-cadence = "0.5"

Usage

The Metric Sink constructors return a tuple consisting of the sink instance itself as well as a future, which the application must drive to completion; e.g., spawn it in a Tokio task pool.

use cadence::prelude::*;
use cadence::{StatsdClient, DEFAULT_PORT};
use tokio_cadence::TokioBatchUdpMetricSink;
use tokio::{spawn, net::UdpSocket};

#[tokio::main]
async fn main() -> cadence::MetricResult<()> {
    let host = ("metrics.example.com", DEFAULT_PORT);
    let socket = UdpSocket::bind("0.0.0.0:0").await?;
    let (sink, process) = TokioBatchUdpMetricSink::from(host, socket)?;

    // Spawn the future!
    let processing_job = spawn(process);

    {
        let client = StatsdClient::from_sink("my.metrics", sink);

        // Emit metrics!
        client.incr("some.counter");
        client.time("some.methodCall", 42);
        client.gauge("some.thing", 7);
        client.meter("some.value", 5);

        // the client drops here, and the sink along with it
    }

    // Wait for the processing job to complete!
    processing_job.await.unwrap();
    Ok(())
}

Note that in order to ensure that all buffered metrics are submitted, the application must await the completion of the processing job after the client, as well as the sink along with it, are dropped.

License

Licensed under the MIT license.