#statsd-metrics #statsd #metrics #udp

cadence-macros

Macros for Cadence, an extensible Statsd client for Rust

12 releases (6 stable)

1.5.0 Sep 27, 2024
1.4.0 Apr 28, 2024
1.3.0 Mar 23, 2024
1.0.0 Dec 2, 2023
0.25.0 Mar 21, 2021

#318 in Debugging

Download history 64604/week @ 2024-12-08 81533/week @ 2024-12-15 16488/week @ 2024-12-22 36497/week @ 2024-12-29 89483/week @ 2025-01-05 122502/week @ 2025-01-12 128626/week @ 2025-01-19 159213/week @ 2025-01-26 167892/week @ 2025-02-02 192621/week @ 2025-02-09 112874/week @ 2025-02-16 81003/week @ 2025-02-23 410411/week @ 2025-03-02 332244/week @ 2025-03-09 576780/week @ 2025-03-16 768760/week @ 2025-03-23

2,096,906 downloads per month
Used in 4 crates

Apache-2.0/MIT

255KB
3.5K SLoC

cadence-macros

build status docs.rs crates.io Rust 1.60+

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.

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

use std::net::UdpSocket;
use std::time::Duration;
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("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);

// Set the default client to use for macro calls
cadence_macros::set_global_default(client);

// 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_time!("some.timer", Duration::from_millis(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_gauge!("some.gauge", 123.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_histogram!("some.histogram", Duration::from_nanos(123), "tag" => "val", "another" => "thing");
statsd_histogram!("some.histogram", 123.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_distribution!("some.distribution", 123.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");

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.

Dependencies

~350KB