Cadence

An extensible Statsd client for Rust!

Cadence is a fast and flexible way to emit Statsd metrics from your application.

Features

Support for emitting counters, timers, histograms, distributions, gauges, meters, and sets to Statsd over UDP (or optionally Unix sockets).
Support for alternate backends via the MetricSink trait.
Support for Datadog style metrics tags and extensions.
Macros to simplify common calls to emit metrics
A simple yet flexible API for sending metrics.

Usage

An example of how to use Cadence for maximum performance is given below. For many more examples and advanced use cases, see the cadence crate or the documentation.

use std::net::UdpSocket;
use cadence::prelude::*;
use cadence::{StatsdClient, QueuingMetricSink, BufferedUdpMetricSink, 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 udp_sink = BufferedUdpMetricSink::from(host, socket).unwrap();
let queuing_sink = QueuingMetricSink::from(udp_sink);
let client = StatsdClient::from_sink("my.prefix", queuing_sink);

client.count("my.counter.thing", 29);
client.time("my.service.call", 214);

Project layout

The cadence crate contains the Statsd client and primary API of Cadence. The cadence-macros crate contains optional macros that can simplify use of the Cadence API.

cadence: Statsd client and primary API
cadence-macros: Optional convenience macros

Documentation

The documentation is available at https://docs.rs/cadence/ or https://docs.rs/cadence-macros/

Source

The source code is available on GitHub at https://github.com/56quarters/cadence

Changes

Release notes for Cadence can be found in the CHANGES.md file.

Development

Cadence uses Cargo for performing various development tasks.

To build Cadence:

$ cargo build

To run tests:

$ cargo test

or:

$ cargo test -- --ignored

To run benchmarks:

$ cargo bench

To build documentation:

$ cargo doc

License

Cadence is licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Example code in Cadence (cadence/examples or cadence-macros/examples) is available under the CC0 Public Domain Dedication (LICENSE-CC0 or https://creativecommons.org/share-your-work/public-domain/cc0/).

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.

Language Support

Cadence (latest master) supports building with a range of 1.60+ versions.

Guaranteed to Build

The latest version of Cadence is tested against and will always build correctly with

The current stable version.
The previous two stable versions, stable - 1 and stable - 2.

Best Effort Build

The latest version of Cadence is tested against and will usually build correctly with

The next two oldest stable versions, stable - 3 and stable - 4.

Support for these versions may be dropped for a release in order to take advantage of a feature available in newer versions of Rust.

Known to Work

Stable versions as far back as 1.41 are known to work with Cadence 0.26.0 through 0.29.0.
Stable versions as far back as 1.36 are known to work with Cadence 0.21.0 through 0.25.0.
Stable versions as far back as 1.34 are known to work with Cadence 0.20.0.
Stable versions as far back as 1.32 are known to work with Cadence 0.19.0.
Stable versions as far back as 1.31 are known to work with Cadence 0.18.0.

56quarters / cadence

readme