[−][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.

Overview

metrics exposes two main concepts: emitting a metric, and recording it.

Emission

Metrics are emitted by utilizing the registration or emission macros. There is a macro for registering and emitting each fundamental metric type:

In order to register or emit a metric, you need a way to record these events, which is where Recorder comes into play.

Recording

The Recorder trait defines the interface between the registration/emission macros, and exporters, which is how we refer to concrete implementations of Recorder. The trait defines what the exporters are doing -- recording -- but ultimately exporters are sending data from your application to somewhere else: whether it be a third-party service or logging via standard out. It's "exporting" the metric data somewhere else besides your application.

Each metric type is usually reserved for a specific type of use case, whether it be tracking a single value or allowing the summation of multiple values, and the respective macros elaborate more on the usage and invariants provided by each.

Getting Started

In libraries

Libraries need only include the metrics crate to emit metrics. When an executable installs a recorder, all included crates which emitting metrics will now emit their metrics to that record, which allows library authors to seamless emit their own metrics without knowing or caring which exporter implementation is chosen, or even if one is installed.

In cases where no global recorder is installed, a "noop" recorder lives in its place, which has an incredibly very low overhead: an atomic load and comparison. Libraries can safely instrument their code without fear of ruining baseline performance.

Examples

use metrics::{histogram, counter};

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

    histogram!("process.query_time", delta);
    counter!("process.query_row_count", row_count);

    row_count
}

In executables

Executables, which themselves can emit their own metrics, are intended to install a global recorder so that metrics can actually be recorded and exported somewhere.

Initialization of the global recorder isn't required for macros to function, but any metrics emitted before a global recorder is installed will not be recorded, so early initialization is recommended when possible.

Warning

The metrics system may only be initialized once.

For most use cases, you'll be using an off-the-shelf exporter implementation that hooks up to an existing metrics collection system, or interacts with the existing systems/processes that you use.

Out of the box, some exporter implementations are available for you to use:

You can also implement your own recorder if a suitable one doesn't already exist.

Development

The primary interface with metrics is through the Recorder trait, so we'll show examples below of the trait and implementation notes.

Implementing and installing a basic recorder

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

use log::info;
use metrics::{GaugeValue, Key, Recorder, Unit};
use metrics::SetRecorderError;

struct LogRecorder;

impl Recorder for LogRecorder {
    fn register_counter(&self, key: Key, _unit: Option<Unit>, _description: Option<&'static str>) {}

    fn register_gauge(&self, key: Key, _unit: Option<Unit>, _description: Option<&'static str>) {}

    fn register_histogram(&self, key: Key, _unit: Option<Unit>, _description: Option<&'static str>) {}

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

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

    fn record_histogram(&self, key: Key, value: f64) {
        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:

static RECORDER: LogRecorder = LogRecorder;

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

Keys

All metrics are, in essence, the combination of a metric type and metric identifier, such as a histogram called "response_latency". You could conceivably have multiple metrics with the same name, so long as they are of different types.

As the types are enforced/limited by the Recorder trait itself, the remaining piece is the identifier, which we handle by using Key.

Key itself is a wrapper for KeyData, which holds not only the name of a metric, but potentially holds labels for it as well. The name of a metric must always be a literal string. The labels are a key/value pair, where both components are strings as well.

Internally, metrics uses a clone-on-write "smart pointer" for these values to optimize cases where the values are static strings, which can provide significant performance benefits. These smart pointers can also hold owned String values, though, so users can mix and match static strings and owned strings for labels without issue. Metric names, as mentioned above, are always static strings.

Two Key objects can be checked for equality and considered to point to the same metric if they are equal. Equality checks both the name of the key and the labels of a key. Labels are not sorted prior to checking for equality, but insertion order is maintained, so any Key constructed from the same set of labels in the same order should be equal.

It is an implementation detail if a recorder wishes to do an deeper equality check that ignores the order of labels, but practically speaking, metric emission, and thus labels, should be fixed in ordering in nearly all cases, and so it isn't typically a problem.

Registration

Recorders must handle the "registration" of a metric.

In practice, registration solves two potential problems: providing metadata for a metric, and creating an entry for a metric even though it has not been emitted yet.

Callers may wish to provide a human-readable description of what the metric is, or provide the units the metrics uses. Additionally, users may wish to register their metrics so that they show up in the output of the installed exporter even if the metrics have yet to be emitted. This allows callers to ensure the metrics output is stable, or allows them to expose all of the potential metrics a system has to offer, again, even if they have not all yet been emitted.

As you can see from the trait, the registration methods treats the metadata as optional, and the macros allow users to mix and match whichever fields they want to provide.

When a metric is registered, the expectation is that it will show up in output with a default value, so, for example, a counter should be initialized to zero, a histogram would have no values, and so on.

Emission

Likewise, records must handle the emission of metrics as well.

Comparatively speaking, emission is not too different from registration: you have access to the same Key as well as the value being emitted.

For recorders which temporarily buffer or hold on to values before exporting, a typical approach would be to utilize atomic variables for the storage. For counters and gauges, this can be done simply by using types like AtomicU64. For histograms, this can be slightly tricky as you must hold on to all of the distinct values. In our helper crate, metrics-util, we've provided a type called AtomicBucket. For exporters that will want to get all of the current values in a batch, while clearing the bucket so that values aren't processed again, AtomicBucket provides a simple interface to do so, as well as optimized performance on both the insertion and read side.

Installing recorders

In order to actually use an exporter, it must be installed as the "global" recorder. This is a static recorder that the registration and emission macros refer to behind-the-scenes. metrics provides a few methods to do so: set_recorder, set_boxed_recorder, and set_recorder_racy.

Primarily, you'll use set_boxed_recorder to pass a boxed version of the exporter to be installed. This is due to the fact that most exporters won't be able to be constructed statically. If you could construct your exporter statically, though, then you could instead choose set_recorder.

Similarly, set_recorder_racy takes a static reference, but is also not thread safe, and should only be used on platforms which do not support atomic operations, such as embedded environments.

Macros

counter

Increments a counter.

decrement_gauge

Decrements a gauge.

gauge

Updates a gauge.

histogram

Records a histogram.

increment_counter

Increments a counter by one.

increment_gauge

Increments a gauge.

register_counter

Registers a counter.

register_gauge

Registers a gauge.

register_histogram

Records a histogram.

Structs

KeyData

Inner representation of Key.

Label

Metadata for a metric key in the for of a key/value pair.

NameParts

Parts compromising a metric name.

NoopRecorder

A no-op recorder.

SetRecorderError

The type returned by set_recorder if set_recorder has already been called.

Enums

GaugeValue

Value of a gauge operation.

Key

A metric identifier.

Unit

Units for a given metric.

Traits

IntoF64

An object which can be converted into a f64 representation.

IntoLabels

A value that can be converted to a vector of Labels.

Recorder

A trait for registering and recording metrics.

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.

Type Definitions

SharedString

An allocation-optimized string.