mirror of https://github.com/fralalonde/dipstick
Merge branch 'master' into fix/api-cleanup-named-etc
This commit is contained in:
commit
bae0fa6b5a
|
@ -11,7 +11,7 @@ documentation = "https://docs.rs/dipstick"
|
|||
homepage = "https://github.com/fralalonde/dipstick"
|
||||
repository = "https://github.com/fralalonde/dipstick"
|
||||
readme = "README.md"
|
||||
keywords = ["metrics", "statsd", "graphite", "timer", "monitoring"]
|
||||
keywords = ["metrics", "statsd", "graphite", "timer", "prometheus"]
|
||||
license = "MIT/Apache-2.0"
|
||||
|
||||
[badges]
|
||||
|
|
72
HANDBOOK.md
72
HANDBOOK.md
|
@ -53,17 +53,21 @@ Usable either through the time! macro, the closure form or explicit calls to sta
|
|||
While timers internal precision are in nanoseconds, their accuracy depends on platform OS and hardware.
|
||||
Timer's default output format is milliseconds but is scalable up or down.
|
||||
|
||||
```$rust,skt-run
|
||||
let app_metrics = Stream::to_stdout().metrics();
|
||||
let timer = app_metrics.timer("my_timer");
|
||||
time!(timer, {/* slow code here */} );
|
||||
timer.time(|| {/* slow code here */} );
|
||||
|
||||
let start = timer.start();
|
||||
/* slow code here */
|
||||
timer.stop(start);
|
||||
|
||||
timer.interval_us(123_456);
|
||||
```rust
|
||||
extern crate dipstick;
|
||||
use dipstick::*;
|
||||
fn main() {
|
||||
let app_metrics = Stream::to_stdout().metrics();
|
||||
let timer = app_metrics.timer("my_timer");
|
||||
time!(timer, {/* slow code here */} );
|
||||
timer.time(|| {/* slow code here */} );
|
||||
|
||||
let start = timer.start();
|
||||
/* slow code here */
|
||||
timer.stop(start);
|
||||
|
||||
timer.interval_us(123_456);
|
||||
}
|
||||
```
|
||||
|
||||
### Level
|
||||
|
@ -84,11 +88,15 @@ Aggregated statistics may also append identifiers to the metric's name.
|
|||
Names should exclude characters that can interfere with namespaces, separator and output protocols.
|
||||
A good convention is to stick with lowercase alphanumeric identifiers of less than 12 characters.
|
||||
|
||||
```$rust,skt-run
|
||||
let app_metrics = Stream::to_stdout().metrics();
|
||||
let db_metrics = app_metrics.named("database");
|
||||
let _db_timer = db_metrics.timer("db_timer");
|
||||
let _db_counter = db_metrics.counter("db_counter");
|
||||
```rust
|
||||
extern crate dipstick;
|
||||
use dipstick::*;
|
||||
fn main() {
|
||||
let app_metrics = Stream::to_stdout().metrics();
|
||||
let db_metrics = app_metrics.named("database");
|
||||
let _db_timer = db_metrics.timer("db_timer");
|
||||
let _db_counter = db_metrics.counter("db_counter");
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
@ -112,13 +120,17 @@ Notes about labels:
|
|||
|
||||
Metric inputs are usually setup statically upon application startup.
|
||||
|
||||
```$rust,skt-run
|
||||
```rust
|
||||
#[macro_use]
|
||||
extern crate dipstick;
|
||||
use dipstick::*;
|
||||
|
||||
metrics!("my_app" => {
|
||||
COUNTER_A: Counter = "counter_a";
|
||||
});
|
||||
|
||||
fn main() {
|
||||
Proxy::set_default_target(Stream::to_stdout().metrics());
|
||||
Proxy::default_target(Stream::to_stdout().metrics());
|
||||
COUNTER_A.count(11);
|
||||
}
|
||||
```
|
||||
|
@ -130,10 +142,15 @@ The static metric definition macro is just `lazy_static!` wrapper.
|
|||
If necessary, metrics can also be defined "dynamically".
|
||||
This is more flexible but has a higher runtime cost, which may be alleviated with the optional caching mechanism.
|
||||
|
||||
```$rust,skt-run
|
||||
let user_name = "john_day";
|
||||
let app_metrics = Log::to_log().cached(512).metrics();
|
||||
app_metrics.gauge(&format!("gauge_for_user_{}", user_name)).value(44);
|
||||
<<<<<<< HEAD
|
||||
```rust
|
||||
extern crate dipstick;
|
||||
use dipstick::*;
|
||||
fn main() {
|
||||
let user_name = "john_day";
|
||||
let app_metrics = Log::to_log().cached(512).metrics();
|
||||
app_metrics.gauge(&format!("gauge_for_user_{}", user_name)).value(44);
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, you may use `Labels` to output context-dependent metrics.
|
||||
|
@ -186,11 +203,16 @@ If enabled, buffering is usually a best-effort affair, to safely limit the amoun
|
|||
Some outputs such as statsd also have the ability to sample metrics.
|
||||
If enabled, sampling is done using pcg32, a fast random algorithm with reasonable entropy.
|
||||
|
||||
```$rust,skt-run,no_run
|
||||
let _app_metrics = Statsd::send_to("server:8125")?.sampled(Sampling::Random(0.01)).metrics();
|
||||
```rust
|
||||
extern crate dipstick;
|
||||
use dipstick::*;
|
||||
fn main() {
|
||||
let _app_metrics = Statsd::send_to("localhost:8125").expect("connected")
|
||||
.sampled(Sampling::Random(0.01))
|
||||
.metrics();
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Intermediates
|
||||
|
||||
### Proxy
|
||||
|
|
|
@ -1,17 +0,0 @@
|
|||
Templates
|
||||
|
||||
Use `cargo test --features="skeptic"` to run the examples in the README using the `skeptic` crate.
|
||||
|
||||
```rust,skt-run
|
||||
#[macro_use]
|
||||
extern crate dipstick;
|
||||
use dipstick::*;
|
||||
fn main() -> std::result::Result<(), Box<std::error::Error>> {{
|
||||
{}
|
||||
Ok(())
|
||||
}}
|
||||
```
|
||||
|
||||
```rust,skt-plain
|
||||
{}
|
||||
```
|
25
README.md
25
README.md
|
@ -44,24 +44,33 @@ These are all best done by downstream timeseries visualization and monitoring to
|
|||
|
||||
Here's a basic aggregating & auto-publish counter metric:
|
||||
|
||||
```$rust,skt-run
|
||||
let bucket = AtomicBucket::new();
|
||||
bucket.set_drain(Stream::to_stdout());
|
||||
bucket.flush_every(std::time::Duration::from_secs(3));
|
||||
let counter = bucket.counter("counter_a");
|
||||
counter.count(8);
|
||||
```rust
|
||||
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:
|
||||
|
||||
```$rust,skt-run
|
||||
```rust
|
||||
#[macro_use]
|
||||
extern crate dipstick;
|
||||
use dipstick::*;
|
||||
|
||||
metrics! { METRICS = "my_app" => {
|
||||
pub COUNTER: Counter = "my_counter";
|
||||
}
|
||||
}
|
||||
|
||||
fn main() {
|
||||
METRICS.target(Graphite::send_to("localhost:2003").unwrap().metrics());
|
||||
METRICS.set_target(Graphite::send_to("localhost:2003").expect("connected").metrics());
|
||||
COUNTER.count(32);
|
||||
}
|
||||
```
|
||||
|
|
|
@ -1,17 +0,0 @@
|
|||
Templates
|
||||
|
||||
Use `cargo test --features="skeptic"` to run the examples in the README using the `skeptic` crate.
|
||||
|
||||
```rust,skt-run
|
||||
#[macro_use]
|
||||
extern crate dipstick;
|
||||
use dipstick::*;
|
||||
fn main() -> std::result::Result<(), Box<std::error::Error>> {{
|
||||
{}
|
||||
Ok(())
|
||||
}}
|
||||
```
|
||||
|
||||
```rust,skt-plain
|
||||
{}
|
||||
```
|
|
@ -117,7 +117,7 @@ impl InnerAtomicBucket {
|
|||
|
||||
let stats_fn = match self.stats {
|
||||
Some(ref stats_fn) => stats_fn.clone(),
|
||||
None => DEFAULT_AGGREGATE_STATS.read()?.clone(),
|
||||
None => DEFAULT_AGGREGATE_STATS.read().expect("Aggregator").clone(),
|
||||
};
|
||||
|
||||
for metric in snapshot {
|
||||
|
|
|
@ -26,7 +26,7 @@ impl TimeHandle {
|
|||
(duration.as_secs() * 1_000_000) + duration.subsec_micros() as u64
|
||||
}
|
||||
|
||||
/// Get the elapsed time in microseconds since TimeHandle was obtained.
|
||||
/// Get the elapsed time in milliseconds since TimeHandle was obtained.
|
||||
pub fn elapsed_ms(self) -> MetricValue {
|
||||
(self.elapsed_us() / 1000) as isize
|
||||
}
|
||||
|
|
|
@ -1,5 +1,6 @@
|
|||
use std::error::Error;
|
||||
use std::result;
|
||||
use std::error;
|
||||
|
||||
/// Just put any error in a box.
|
||||
pub type Result<T> = result::Result<T, Box<Error>>;
|
||||
pub type Result<T> = result::Result<T, Box<error::Error + Send + Sync>>;
|
||||
|
||||
|
|
|
@ -141,12 +141,12 @@ impl Marker {
|
|||
}
|
||||
|
||||
/// A counter of absolute observed values (non-negative amounts).
|
||||
/// Used to count to count things that can not be undone:
|
||||
/// Used to count things that cannot be undone:
|
||||
/// - Bytes sent
|
||||
/// - Records written
|
||||
/// - Apples eaten
|
||||
/// For relative (possibly negative) values, the `Level` counter type can be used.
|
||||
/// If ag0gregated, minimum and maximum scores will track the collected values, not their sum.
|
||||
/// If aggregated, minimum and maximum scores will track the collected values, not their sum.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct Counter {
|
||||
inner: InputMetric,
|
||||
|
@ -160,7 +160,7 @@ impl Counter {
|
|||
}
|
||||
|
||||
/// A counter of fluctuating resources accepting positive and negative values.
|
||||
/// Can be used as a stateful `Gauge` or a as `Counter` of possibly decreasing amounts.
|
||||
/// Can be used as a stateful `Gauge` or as a `Counter` of possibly decreasing amounts.
|
||||
/// - Size of messages in a queue
|
||||
/// - Strawberries on a conveyor belt
|
||||
/// If aggregated, minimum and maximum scores will track the sum of values, not the collected values themselves.
|
||||
|
|
Loading…
Reference in New Issue