Crate cadence_macros[][src]

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.


  • Support for emitting counters, timers, histograms, 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.


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

cadence-macros = "x.y.z"


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.

use std::net::UdpSocket;
use cadence::prelude::*;
use cadence::{StatsdClient, QueuingMetricSink, BufferedUdpMetricSink, DEFAULT_PORT};
use cadence_macros::{statsd_count, statsd_time, statsd_gauge, statsd_meter, statsd_histogram, statsd_distribution, statsd_set};

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

let host = ("", 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);

// Set the default client to use for macro calls

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

statsd_time!("some.timer", 123);
statsd_time!("some.timer", 123, "tag" => "val");
statsd_time!("some.timer", 123, "tag" => "val", "another" => "thing");

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

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

statsd_histogram!("some.histogram", 123);
statsd_histogram!("some.histogram", 123, "tag" => "val");
statsd_histogram!("some.histogram", 123, "tag" => "val", "another" => "thing");

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

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


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()
  • Only a single type of value for each type of metric is supported. For example, only u64 can be used with the statsd_time! macro, not a std::time::Duration. Only u64 can be used with the statsd_gauge! macro, not a f64.



Emit a counter using the default global client, optionally with tags


Emit a distribution using the default global client, optionally with tags


Emit a gauge using the default global client, optionally with tags


Emit a histogram using the default global client, optionally with tags


Emit a meter using the default global client, optionally with tags


Emit a set using the default global client, optionally with tags


Emit a timer using the default global client, optionally with tags



Error indicating that a global default StatsdClient was not set when a call to get_global_default was made.



Get a reference to the global default StatsdClient instance


Return true if the global default StatsdClient is set, false otherwise


Set the global default StatsdClient instance