Macro metrics::register_histogram

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

Records a histogram.

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

Metrics can be registered with an optional unit and description. Whether or not the installed recorder does anything with the description is implementation defined. Labels can also be specified when registering a metric.

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:
register_histogram!("some_metric_name");

// Providing a unit for a histogram:
register_histogram!("some_metric_name", Unit::Nanoseconds);

// Providing a description for a histogram:
register_histogram!("some_metric_name", "request handler duration");

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

// We can combine the units, description, and labels arbitrarily:
register_histogram!("some_metric_name", Unit::Nanoseconds, "request handler duration");
register_histogram!("some_metric_name", Unit::Nanoseconds, "service" => "http");
register_histogram!("some_metric_name", "request handler duration", "service" => "http");

// And all combined:
register_histogram!("some_metric_name", Unit::Nanoseconds, "request handler duration", "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))];
register_histogram!("some_metric_name", &labels);