Macro metrics::histogram

histogram!() { /* proc-macro */ }

Records a histogram.

Histograms measure the distribution of values for a given set of measurements, and start with no initial values.

Implicit conversions

Histograms are represented as f64 values, but often come from another source, such as a time measurement. By default, histogram! will accept a f64 directly or a Duration, which uses the floating-point number of seconds represents by the duration.

External libraries and applications can create their own conversions by implementing the IntoF64 trait for their types, which is required for the value being passed to histogram!.

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:
histogram!("some_metric_name", 34.3);

// An implicit conversion from `Duration`:
let d = Duration::from_millis(17);
histogram!("some_metric_name", d);

// Specifying labels:
histogram!("some_metric_name", 38.0, "service" => "http");

// We can also pass labels by giving a vector or slice of key/value pairs:
let dynamic_val = "woo";
let labels = [("dynamic_key", format!("{}!", dynamic_val))];
histogram!("some_metric_name", 1337.5, &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");
histogram!(name, 800.85);

histogram!(format!("{}_via_format", "name"), 3.14);