Cadence Documentation

Macros Documentation

An extensible Statsd client for Rust!

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

• 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.
• Macros to simplify common calls to emit metrics
• A simple yet flexible API for sending metrics.

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);

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

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

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

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

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

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/).

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.

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

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.

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.

• 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.