Cadence
An extensible Statsd client for Rust!
Features
- Support for emitting counters, timers, gauges, and meters to Statsd over UDP.
- Support for alternate backends via the
MetricSink
trait. - A simple yet flexible API for sending metrics.
Install
To make use of Cadence in your project, add it as a dependency.
[]
= "x.y.z"
Then, link to it in your library or application.
// bin.rs or lib.rs
extern crate cadence;
// rest of your library or application
Usage
Some examples of how to use Cadence are shown below.
Simple Use
Simple usage of Cadence is shown below. In this example, we just import the client, create an instance that will write to some imaginary metrics server, and send a few metrics.
// Import the client.
//
// Note that we're also importing each of the traits that the client uses to emit
// metircs (Counted, Timed, Gauged, and Metered).
use ;
// Create client that will write to the given host over UDP.
//
// Note that you'll probably want to actually handle any errors creating the client
// when you use it for real in your application. We're just using .unwrap() here
// since this is an example!
let host = ;
let client = from_udp_host.unwrap;
// Emit metrics!
client.incr;
client.time;
client.gauge;
client.meter;
Counted, Timed, Gauged, and Metered Traits
Each of the methods that the Cadence StatsdClient
struct uses to send metrics are
implemented as a trait. If we want, we can just use the trait type to refer to the
client instance. This might be useful to you if you'd like to swap out the actual
Cadence client with a dummy version when you are unit testing your code.
use ;
// Here's a simple DAO (Data Access Object) that doesn't do anything but
// uses a counter to keep track of the number of times the 'getUserById'
// method gets called.
Custom Metric Sinks
The Cadence StatsdClient
uses implementations of the MetricSink
trait to
send metrics to a metric server. Most users of the Candence library probably
want to use the UdpMetricSink
implementation. This is the way people typically
interact with a Statsd server, sending packets over UDP.
However, maybe you'd like to do something custom: use a thread pool, send multiple metrics at the same time, or something else. An example of creating a custom sink is below.
use io;
use ;
;
Documentation
The documentation is available at https://tshlabs.github.io/cadence/
Source
The source code is available on GitHub at https://github.com/tshlabs/cadence
Changes
Release notes for Cadence can be found in the CHANGES.md file.