prometheus_utils

Trait Labels

Source 
pub trait Labels {
    // Required methods
    fn label_names() -> Vec<&'static str>;
    fn possible_label_values() -> Vec<LabelValues<'static>> ⓘ;
    fn label_values(&self) -> LabelValues<'_>;
}
Expand description

The Labels trait applies to values intended to generate Prometheus labels for a metric.

A metric in Prometheus can include any number of labels. Each label has a fixed name, and when events are emitted for the metric, those events must include values for each of the labels. Using labels makes it possible to easily see a metric in aggregate (i.e., to see totals regardless of label values), or to query specific kinds of events by filtering label values.

Thus, for example, rather than having a separate metric for each kind of error that arises, we can produce one metric with an “err” label, whose value will reflect which error has occurred. That simplifies the top-level list of metrics, and makes it easier to build queries to aggregate specific kinds of error events.

This trait adds some extra guard rails on top of the prometheus-rs crate, so that when we emit a labeled metric we can use a custom type to represent the labels, rather than working directly with slices of string slices. When defining a labeled metric, you should also define a new type representing its labels that implements the Labels trait. Then, when emitting events for the metric, labels are passed in using this custom type, which rules out several kinds of bugs (like missing or incorrectly ordered label values).

You can define labeled metrics using types like IntCounterWithLabels, which are parameterized by a type that implements Labels.

Required Methods§

Source

fn label_names() -> Vec<&'static str>

The names of the labels that will be defined for the corresponding metric.

Source

fn possible_label_values() -> Vec<LabelValues<'static>> ⓘ

Labels values to seed the metric with initially.

Since Prometheus doesn’t know the possible values a label will take on, when we set up a labeled metric by default no values will appear until events are emitted. But for discoverability, it’s helpful to initialize a labeled metric with some possible label values (at count 0) even if no events for the metric have occurred.

The label values provided by this function are used to pre-populate the metric at count 0. The values do not need to be exhaustive; it’s fine for events to emit label values that are not included here.

Source

fn label_values(&self) -> LabelValues<'_>

The actual label values to provide when emitting an event to Prometheus.

The sequence of values should correspond to the names provided in label_names, in order.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§