Macro metrics::register_gauge

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

Registers a gauge.

Gauges represent a single value that can go up or down over time, and always starts out with an initial value of zero.

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

// Providing a unit for a gauge:
register_gauge!("some_metric_name", Unit::Bytes);

// Providing a description for a gauge:
register_gauge!("some_metric_name", "total number of bytes");

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

// We can combine the units, description, and labels arbitrarily:
register_gauge!("some_metric_name", Unit::Bytes, "total number of bytes");
register_gauge!("some_metric_name", Unit::Bytes, "service" => "http");
register_gauge!("some_metric_name", "total number of bytes", "service" => "http");

// And all combined:
register_gauge!("some_metric_name", Unit::Bytes, "total number of bytes", "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_gauge!("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");
register_gauge!(name);

register_gauge!(format!("{}_via_format", "name"));