#metrics #statsd #graphite #timer #prometheus

dipstick

A fast, all-purpose metrics library decoupling instrumentation from reporting backends. Similar to popular logging frameworks, but with counters, timers and gauges. Can combine outputs (e.g. log + graphite), do sampling, aggregation, periodical publication, etc.

48 releases

✓ Uses Rust 2018 edition

new 0.7.6 May 22, 2019
0.7.3 Apr 16, 2019
0.7.1 Jan 13, 2019
0.6.11 Jun 8, 2018
0.4.11 Nov 29, 2017

#4 in Visualization

Download history 79/week @ 2019-02-06 116/week @ 2019-02-13 105/week @ 2019-02-20 197/week @ 2019-02-27 159/week @ 2019-03-06 113/week @ 2019-03-13 312/week @ 2019-03-20 164/week @ 2019-03-27 125/week @ 2019-04-03 155/week @ 2019-04-10 66/week @ 2019-04-17 117/week @ 2019-04-24 61/week @ 2019-05-01 164/week @ 2019-05-08 163/week @ 2019-05-15

617 downloads per month
Used in 1 crate

MIT/Apache

184KB
4.5K SLoC

crates.io docs.rs Build Status

dipstick a dipstick picture

A one-stop shop metrics library for Rust applications with lots of features,
minimal impact on applications and a choice of output to downstream systems.

Features

Dipstick is a toolkit to help all sorts of application collect and send out metrics. As such, it needs a bit of set up to suit one's needs. Skimming through the handbook and many examples should help you get an idea of the possible configurations.

In short, dipstick-enabled apps can:

  • Send metrics to console, log, statsd, graphite or prometheus (one or many)
  • Locally aggregate the count, sum, mean, min, max and rate of metric values
  • Publish aggregated metrics, on schedule or programmatically
  • Customize output statistics and formatting
  • Define global or scoped (e.g. per request) metrics
  • Statistically sample metrics (statsd)
  • Choose between sync or async operation
  • Choose between buffered or immediate output
  • Switch between metric backends at runtime

For convenience, dipstick builds on stable Rust with minimal, feature-gated dependencies. Performance, safety and ergonomy are also prime concerns.

Non-goals

Dipstick's focus is on metrics collection (input) and forwarding (output). Although it will happily aggregate base statistics, for the sake of simplicity and performance Dipstick will not

  • plot graphs
  • send alerts
  • track histograms

These are all best done by downstream timeseries visualization and monitoring tools.

Show me the code!

Here's a basic aggregating & auto-publish counter metric:

extern crate dipstick;
use dipstick::*;

fn main() {
    let bucket = AtomicBucket::new();
    bucket.drain(Stream::to_stdout());
    bucket.flush_every(std::time::Duration::from_secs(3));
    let counter = bucket.counter("counter_a");
    counter.count(8);
}

Persistent apps wanting to declare static metrics will prefer using the metrics! macro:

extern crate dipstick;
use dipstick::*;

metrics! { METRICS = "my_app" => {
        pub COUNTER: Counter = "my_counter";
    }
}

fn main() {
    METRICS.target(Graphite::send_to("localhost:2003").expect("connected").metrics());
    COUNTER.count(32);
}

For sample applications see the examples. For documentation see the handbook.

To use Dipstick in your project, add the following line to your Cargo.toml in the [dependencies] section:

dipstick = "0.7.6"

External features

Configuring dipstick from a text file is possible using the spirit-dipstick crate.

Building

When building the crate prior to PR or release, just run plain old make. This will in turn run cargo a few times to run tests, benchmarks, lints, etc. Unfortunately, nightly Rust is still required to run bench and clippy.

TODO / Missing / Weak points

  • Prometheus support is still primitive (read untested). Only the push gateway approach is supported for now.
  • No backend for "pull" metrics yet. Should at least provide tiny-http listener capability.
  • No quick integration feature with common frameworks (Actix, etc.) is provided yet.
  • Thread Local buckets could be nice.
  • "Rolling" aggregators would be nice for pull metrics. Current bucket impl resets after flush.

License

Dipstick is licensed under the terms of the Apache 2.0 and MIT license.

Dependencies

~2.5MB
~38K SLoC