[−][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:
register_counter!
,increment!
, andcounter!
for countersregister_gauge!
andgauge!
for gaugesregister_histogram!
andhistogram!
for histograms
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:
- metrics-exporter-tcp - outputs metrics to clients over TCP
- metrics-exporter-prometheus - serves a Prometheus scrape endpoint
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::{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: f64) { 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: 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. |
gauge | Updates a gauge. |
histogram | Records a histogram. |
increment | Increments a counter by one. |
register_counter | Registers a counter. |
register_gauge | Registers a gauge. |
register_histogram | Records a histogram. |
Structs
KeyData | Inner representation of |
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 |
Enums
Key | A metric identifier. |
Unit | Units for a given metric. |
Traits
IntoLabels | A value that can be converted to a vector of |
IntoU64 | An object which can be converted into a |
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 |
set_recorder | Sets the global recorder to a |
set_recorder_racy⚠ | A thread-unsafe version of |
try_recorder | Returns a reference to the recorder. |
Type Definitions
SharedString | An allocation-optimized string. |