[−][src]Crate metrics

A lightweight metrics facade.

The metrics crate provides a single metrics API that abstracts over the actual metrics implementation. Libraries can use the metrics API provided by this crate, and the consumer of those libraries can choose the metrics implementation that is most suitable for its use case.

If no metrics implementation is selected, the facade falls back to a "noop" implementation that ignores all metrics. The overhead in this case is very small - an atomic load and comparison.

Use

The basic use of the facade crate is through the four metrics macros: counter!, gauge!, timing!, and value!. These macros correspond to updating a counter, updating a gauge, updating a histogram based on a start/end, and updating a histogram with a single value.

Both timing! and value! are effectively identical in so far as that they both translate to recording a single value to an underlying histogram, but timing! is provided for contextual consistency: if you're recording a measurement of the time passed during an operation, the end result is a single value, but it's more of a "timing" value than just a "value". The timing! macro also has a branch to accept the start and end values which allows for a potentially clearer invocation.

In libraries

Libraries should link only to the metrics crate, and use the provided macros to record whatever metrics will be useful to downstream consumers.

Examples

use metrics::{timing, counter};

pub fn process(query: &str) -> u64 {
    let start = Instant::now();
    let row_count = run_query(query);
    let end = Instant::now();

    timing!("process.query_time", start, end);
    counter!("process.query_row_count", row_count);

    row_count
}

In executables

Executables should choose a metrics implementation and initialize it early in the runtime of the program. Metrics implementations will typically include a function to do this. Any metrics recordered before the implementation is initialized will be ignored.

The executable itself may use the metrics crate to record metrics well.

Warning

The metrics system may only be initialized once.

Available metrics implementations

Native recorder:
- metrics-runtime

Implementing a Recorder

Recorders implement the Recorder trait. Here's a basic example which writes the metrics in text form via the log crate.

use log::info;
use metrics::Recorder;
use metrics_core::Key;

struct LogRecorder;

impl Recorder for LogRecorder {
    fn increment_counter(&self, key: Key, value: u64) {
        info!("counter '{}' -> {}", key, value);
    }

    fn update_gauge(&self, key: Key, value: i64) {
        info!("gauge '{}' -> {}", key, value);
    }

    fn record_histogram(&self, key: Key, value: u64) {
        info!("histogram '{}' -> {}", key, value);
    }
}

Recorders are installed by calling the set_recorder function. Recorders should provide a function that wraps the creation and installation of the recorder:

use metrics::SetRecorderError;

static RECORDER: LogRecorder = LogRecorder;

pub fn init() -> Result<(), SetRecorderError> {
    metrics::set_recorder(&RECORDER)
}

Use with `std`

set_recorder requires you to provide a &'static Recorder, which can be hard to obtain if your recorder depends on some runtime configuration. The set_boxed_recorder function is available with the std Cargo feature. It is identical to set_recorder except that it takes a Box<Recorder> rather than a &'static Recorder:

use metrics::SetRecorderError;

pub fn init() -> Result<(), SetRecorderError> {
    metrics::set_boxed_recorder(Box::new(LogRecorder))
}

Macros

counter	Increments a counter by a value.
gauge	Update a gauge with a value.
labels	Helper macro for generating a set of labels.
timing	Records a timing.
value	Records a value.

Structs

Key	A metric key.
Label	A key/value pair used to further describe a metric.
SetRecorderError	The type returned by `set_recorder` if `set_recorder` has already been called.

Traits

Recorder

A value that records metrics behind the facade.

Functions

recorder	Returns a reference to the recorder.
set_boxed_recorder	Sets the global recorder to a `Box<Recorder>`.
set_recorder	Sets the global recorder to a `&'static Recorder`.
set_recorder_racy ^⚠	A thread-unsafe version of `set_recorder`.
try_recorder	Returns a reference to the recorder.