cadence_macros/
lib.rs

1// Cadence - An extensible Statsd client for Rust!
2//
3// Copyright 2020-2021 Nick Pillitteri
4//
5// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8// option. This file may not be copied, modified, or distributed
9// except according to those terms.
10
11//! An extensible Statsd client for Rust!
12//!
13//! Cadence is a fast and flexible way to emit Statsd metrics from your application.
14//! The `cadence-macros` crate provides some wrappers to eliminate much of the boilerplate
15//! that is often needed to emit metrics along with any tags that are associated with
16//! them.
17//!
18//! ## Features
19//!
20//! * [Support](https://docs.rs/cadence/) for emitting counters, timers, histograms, distributions,
21//!   gauges, meters, and sets to Statsd over UDP (or optionally Unix sockets).
22//! * Support for alternate backends via the `MetricSink` trait.
23//! * Support for [Datadog](https://docs.datadoghq.com/developers/dogstatsd/) style metrics tags.
24//! * [Macros](https://docs.rs/cadence-macros/) to simplify common calls to emit metrics
25//! * A simple yet flexible API for sending metrics.
26//!
27//! ## Install
28//!
29//! To make use of `cadence-macros` in your project, add it as a dependency in your `Cargo.toml` file.
30//!
31//! ```toml
32//! [dependencies]
33//! cadence-macros = "x.y.z"
34//! ```
35//!
36//! ## Usage
37//!
38//! To make use of the macros in this crate, you'll need to set a global default Statsd client.
39//! Configure a `cadence::StatsdClient` as usual and use the `set_global_default` function to
40//! set it as the default. After that, you can make use of the macros in this crate.
41//!
42//! ```rust,no_run
43//! use std::net::UdpSocket;
44//! use std::time::Duration;
45//! use cadence::prelude::*;
46//! use cadence::{StatsdClient, QueuingMetricSink, BufferedUdpMetricSink, DEFAULT_PORT};
47//! use cadence_macros::{statsd_count, statsd_time, statsd_gauge, statsd_meter, statsd_histogram, statsd_distribution, statsd_set};
48//!
49//! // Normal setup for a high-performance Cadence instance
50//! let socket = UdpSocket::bind("0.0.0.0:0").unwrap();
51//! socket.set_nonblocking(true).unwrap();
52//!
53//! let host = ("metrics.example.com", DEFAULT_PORT);
54//! let udp_sink = BufferedUdpMetricSink::from(host, socket).unwrap();
55//! let queuing_sink = QueuingMetricSink::from(udp_sink);
56//! let client = StatsdClient::from_sink("my.prefix", queuing_sink);
57//!
58//! // Set the default client to use for macro calls
59//! cadence_macros::set_global_default(client);
60//!
61//! // Macros!
62//! statsd_count!("some.counter", 123);
63//! statsd_count!("some.counter", 123, "tag" => "val");
64//! statsd_count!("some.counter", 123, "tag" => "val", "another" => "thing");
65//!
66//! statsd_time!("some.timer", 123);
67//! statsd_time!("some.timer", 123, "tag" => "val");
68//! statsd_time!("some.timer", 123, "tag" => "val", "another" => "thing");
69//! statsd_time!("some.timer", Duration::from_millis(123), "tag" => "val", "another" => "thing");
70//!
71//! statsd_gauge!("some.gauge", 123);
72//! statsd_gauge!("some.gauge", 123, "tag" => "val");
73//! statsd_gauge!("some.gauge", 123, "tag" => "val", "another" => "thing");
74//! statsd_gauge!("some.gauge", 123.123, "tag" => "val", "another" => "thing");
75//!
76//! statsd_meter!("some.meter", 123);
77//! statsd_meter!("some.meter", 123, "tag" => "val");
78//! statsd_meter!("some.meter", 123, "tag" => "val", "another" => "thing");
79//!
80//! statsd_histogram!("some.histogram", 123);
81//! statsd_histogram!("some.histogram", 123, "tag" => "val");
82//! statsd_histogram!("some.histogram", 123, "tag" => "val", "another" => "thing");
83//! statsd_histogram!("some.histogram", Duration::from_nanos(123), "tag" => "val", "another" => "thing");
84//! statsd_histogram!("some.histogram", 123.123, "tag" => "val", "another" => "thing");
85//!
86//! statsd_distribution!("some.distribution", 123);
87//! statsd_distribution!("some.distribution", 123, "tag" => "val");
88//! statsd_distribution!("some.distribution", 123, "tag" => "val", "another" => "thing");
89//! statsd_distribution!("some.distribution", 123.123, "tag" => "val", "another" => "thing");
90//!
91//! statsd_set!("some.set", 123);
92//! statsd_set!("some.set", 123, "tag" => "val");
93//! statsd_set!("some.set", 123, "tag" => "val", "another" => "thing");
94//! ```
95//!
96//! ## Limitations
97//!
98//! Some limitations with the current implemenation of Cadence macros are described below
99//!
100//! * Value tags are not supported. For example the following style of tag cannot be
101//!   set when using macros: `client.count_with_tags("some.counter", 123).with_tag_value("beta").send()`
102//!
103
104pub use crate::state::{
105    get_global_default, is_global_default_set, set_global_default, GlobalDefaultNotSet, SingletonHolder,
106};
107
108mod macros;
109mod state;
cadence_macros/lib.rs

cadence_macros/
lib.rs
