2018-01-08 05:32:32 +00:00
|
|
|
[![crates.io](https://img.shields.io/crates/v/dipstick.svg)](https://crates.io/crates/dipstick)
|
2018-09-19 20:38:17 +00:00
|
|
|
[![docs.rs](https://docs.rs/dipstick/badge.svg)](https://docs.rs/dipstick)
|
|
|
|
[![Build Status](https://travis-ci.org/fralalonde/dipstick.svg?branch=master)](https://travis-ci.org/fralalonde/dipstick)
|
|
|
|
|
2018-09-27 17:29:42 +00:00
|
|
|
# dipstick ![a dipstick picture](https://raw.githubusercontent.com/fralalonde/dipstick/master/assets/dipstick_single_ok_horiz_transparent_small.png)
|
2018-09-19 20:38:17 +00:00
|
|
|
|
2018-09-20 14:58:21 +00:00
|
|
|
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.
|
2018-09-19 20:38:17 +00:00
|
|
|
|
2017-12-07 21:23:47 +00:00
|
|
|
## Features
|
2017-09-29 20:45:09 +00:00
|
|
|
|
2018-09-20 14:58:21 +00:00
|
|
|
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.
|
2018-11-02 00:16:44 +00:00
|
|
|
Skimming through the [handbook](https://github.com/fralalonde/dipstick/tree/master/HANDBOOK.md)
|
2018-11-12 13:42:19 +00:00
|
|
|
and many [examples](https://github.com/fralalonde/dipstick/tree/master/examples)
|
2018-09-20 14:58:21 +00:00
|
|
|
should help you get an idea of the possible configurations.
|
|
|
|
|
|
|
|
In short, dipstick-enabled apps _can_:
|
2018-09-19 20:38:17 +00:00
|
|
|
|
|
|
|
- Send metrics to console, log, statsd, graphite or prometheus (one or many)
|
|
|
|
- Serve metrics over HTTP
|
2018-09-19 20:54:56 +00:00
|
|
|
- Locally aggregate the count, sum, mean, min, max and rate of metric values
|
|
|
|
- Publish aggregated metrics, on schedule or programmatically
|
2018-09-19 20:38:17 +00:00
|
|
|
- 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
|
2018-09-19 20:54:56 +00:00
|
|
|
- Switch between metric backends at runtime
|
|
|
|
|
2018-09-20 14:58:21 +00:00
|
|
|
For convenience, dipstick builds on stable Rust with minimal, feature-gated dependencies.
|
|
|
|
|
2018-09-19 20:38:17 +00:00
|
|
|
### Non-goals
|
2018-06-28 21:16:16 +00:00
|
|
|
|
2018-11-02 00:16:44 +00:00
|
|
|
Dipstick's focus is on metrics collection (input) and forwarding (output).
|
2018-11-13 14:09:09 +00:00
|
|
|
Although it will happily aggregate base statistics, for the sake of simplicity and performance Dipstick will not
|
2018-09-19 20:38:17 +00:00
|
|
|
- plot graphs
|
|
|
|
- send alerts
|
|
|
|
- track histograms
|
2018-09-19 20:54:56 +00:00
|
|
|
|
2018-09-20 14:58:21 +00:00
|
|
|
These are all best done by downstream timeseries visualization and monitoring tools.
|
2018-06-28 21:16:16 +00:00
|
|
|
|
2018-09-19 20:38:17 +00:00
|
|
|
## Show me the code!
|
2018-06-28 21:16:16 +00:00
|
|
|
|
2018-09-19 20:38:17 +00:00
|
|
|
Here's a basic aggregating & auto-publish counter metric:
|
2018-09-19 20:54:56 +00:00
|
|
|
|
2018-06-28 21:16:16 +00:00
|
|
|
```$rust,skt-run
|
2018-11-13 14:09:09 +00:00
|
|
|
let bucket = AtomicBucket::new();
|
2018-10-18 14:10:23 +00:00
|
|
|
bucket.set_target(Stream::stdout());
|
2018-09-19 20:38:17 +00:00
|
|
|
bucket.flush_every(Duration::from_secs(3));
|
|
|
|
let counter = bucket.counter("counter_a");
|
2018-06-28 21:16:16 +00:00
|
|
|
counter.count(8)
|
|
|
|
```
|
|
|
|
|
2018-09-19 20:38:17 +00:00
|
|
|
Persistent apps wanting to declare static metrics will prefer using the `metrics!` macro:
|
2018-06-28 21:16:16 +00:00
|
|
|
|
2018-09-19 20:38:17 +00:00
|
|
|
```$rust,skt-run
|
2018-10-18 14:10:23 +00:00
|
|
|
metrics! { METRICS = "my_app" => {
|
|
|
|
pub COUNTER: Counter = "my_counter";
|
|
|
|
}
|
2018-09-19 20:38:17 +00:00
|
|
|
}
|
2018-06-28 21:16:16 +00:00
|
|
|
|
2018-09-19 20:38:17 +00:00
|
|
|
fn main() {
|
2018-10-18 14:10:23 +00:00
|
|
|
METRICS.set_target(Graphite::send_to("graphite.com:2003").unwrap().input());
|
2018-09-19 20:38:17 +00:00
|
|
|
COUNTER.count(32);
|
2018-09-19 20:54:56 +00:00
|
|
|
}
|
2018-06-28 21:16:16 +00:00
|
|
|
```
|
2017-09-29 20:45:09 +00:00
|
|
|
|
2018-06-28 21:16:16 +00:00
|
|
|
For sample applications see the [examples](https://github.com/fralalonde/dipstick/tree/master/examples).
|
2018-11-13 14:09:09 +00:00
|
|
|
For documentation see the [handbook](https://github.com/fralalonde/dipstick/tree/master/HANDBOOK.md).
|
2017-07-24 20:36:23 +00:00
|
|
|
|
2018-01-08 05:32:32 +00:00
|
|
|
To use Dipstick in your project, add the following line to your `Cargo.toml`
|
|
|
|
in the `[dependencies]` section:
|
|
|
|
|
|
|
|
```toml
|
2018-09-19 20:38:17 +00:00
|
|
|
dipstick = "0.7.0"
|
2017-09-28 22:17:16 +00:00
|
|
|
```
|
|
|
|
|
2018-01-08 05:32:32 +00:00
|
|
|
## License
|
|
|
|
|
|
|
|
Dipstick is licensed under the terms of the Apache 2.0 and MIT license.
|