macro_rules! histogram { (target: $target:expr, level: $level:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { ... }; (target: $target:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { ... }; (level: $level:expr, $name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { ... }; ($name:expr $(, $label_key:expr $(=> $label_value:expr)?)* $(,)?) => { ... }; }
Expand description
Registers a histogram.
Histograms measure the distribution of values for a given set of measurements, and start with no initial values.
Metrics can be registered, which provides a handle to directly update that metric. For
histograms, Histogram is provided which can record values.
Metric names are shown below using string literals, but they can also be owned String values,
which includes using macros such as format! directly at the callsite. String literals are
preferred for performance where possible.
§Example
// A basic histogram:
let histogram = histogram!("some_metric_name");
histogram.record(1.0);
// Specifying labels inline, including using constants for either the key or value:
let histogram = histogram!("some_metric_name", "service" => "http");
const SERVICE_LABEL: &'static str = "service";
const SERVICE_HTTP: &'static str = "http";
let histogram = histogram!("some_metric_name", SERVICE_LABEL => SERVICE_HTTP);
// We can also pass labels by giving a vector or slice of key/value pairs. In this scenario,
// a unit or description can still be passed in their respective positions:
let dynamic_val = "woo";
let labels = [("dynamic_key", format!("{}!", dynamic_val))];
let histogram = histogram!("some_metric_name", &labels);
// As mentioned in the documentation, metric names also can be owned strings, including ones
// generated at the callsite via things like `format!`:
let name = String::from("some_owned_metric_name");
let histogram = histogram!(name);
let histogram = histogram!(format!("{}_via_format", "name"));