cadence-macros

Cadence Documentation

Macros Documentation

An extensible Statsd client for Rust!

Cadence is a fast and flexible way to emit Statsd metrics from your application. The cadence-macros crate provides some wrappers to eliminate much of the boilerplate that is often needed to emit metrics along with any tags that are associated with them.

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

Install

To make use of cadence-macros in your project, add it as a dependency in your Cargo.toml file.

toml [dependencies] cadence-macros = "x.y.z"

Usage

To make use of the macros in this crate, you'll need to set a global default Statsd client. Configure a cadence::StatsdClient as usual and use the set_global_default function to set it as the default. After that, you can make use of the macros in this crate.

```rust use std::net::UdpSocket; use std::time::Duration; use cadence::prelude::*; use cadence::{StatsdClient, QueuingMetricSink, BufferedUdpMetricSink, DEFAULTPORT}; use cadencemacros::{statsdcount, statsdtime, statsdgauge, statsdmeter, statsdhistogram, statsddistribution, statsd_set};

// Normal setup for a high-performance Cadence instance let socket = UdpSocket::bind("0.0.0.0:0").unwrap(); socket.set_nonblocking(true).unwrap();

let host = ("metrics.example.com", DEFAULTPORT); let udpsink = BufferedUdpMetricSink::from(host, socket).unwrap(); let queuingsink = QueuingMetricSink::from(udpsink); let client = StatsdClient::fromsink("my.prefix", queuingsink);

// Set the default client to use for macro calls cadencemacros::setglobal_default(client);

// Macros! statsdcount!("some.counter", 123); statsdcount!("some.counter", 123, "tag" => "val"); statsd_count!("some.counter", 123, "tag" => "val", "another" => "thing");

statsdtime!("some.timer", 123); statsdtime!("some.timer", 123, "tag" => "val"); statsdtime!("some.timer", 123, "tag" => "val", "another" => "thing"); statsdtime!("some.timer", Duration::from_millis(123), "tag" => "val", "another" => "thing");

statsdgauge!("some.gauge", 123); statsdgauge!("some.gauge", 123, "tag" => "val"); statsdgauge!("some.gauge", 123, "tag" => "val", "another" => "thing"); statsdgauge!("some.gauge", 123.123, "tag" => "val", "another" => "thing");

statsdmeter!("some.meter", 123); statsdmeter!("some.meter", 123, "tag" => "val"); statsd_meter!("some.meter", 123, "tag" => "val", "another" => "thing");

statsdhistogram!("some.histogram", 123); statsdhistogram!("some.histogram", 123, "tag" => "val"); statsdhistogram!("some.histogram", 123, "tag" => "val", "another" => "thing"); statsdhistogram!("some.histogram", Duration::fromnanos(123), "tag" => "val", "another" => "thing"); statsdhistogram!("some.histogram", 123.123, "tag" => "val", "another" => "thing");

statsddistribution!("some.distribution", 123); statsddistribution!("some.distribution", 123, "tag" => "val"); statsddistribution!("some.distribution", 123, "tag" => "val", "another" => "thing"); statsddistribution!("some.distribution", 123.123, "tag" => "val", "another" => "thing");

statsdset!("some.set", 123); statsdset!("some.set", 123, "tag" => "val"); statsd_set!("some.set", 123, "tag" => "val", "another" => "thing"); ```

Limitations

Some limitations with the current implemenation of Cadence macros are described below

• Value tags are not supported. For example the following style of tag cannot be set when using macros: client.count_with_tags("some.counter", 123).with_tag_value("beta").send()

Other

For more information about Cadence, see the README in the repository root.