Loading...
Searching...
No Matches
prometheus::Family< T > Class Template Reference

A metric of type T with a set of labeled dimensions. More...

`#include <family.h>`

Inheritance diagram for prometheus::Family< T >:
[legend]
Collaboration diagram for prometheus::Family< T >:
[legend]

## Public Member Functions

| Family (const std::string &name, const std::string &help, const Labels &constant_labels)
| Create a new metric.
template<typename... Args>
T & | Add (const Labels &labels, Args &&... args)
| Add a new dimensional data.
void | Remove (T *metric)
| Remove the given dimensional data.
bool | Has (const Labels &labels) const
| Returns true if the dimensional data with the given labels exist.
const std::string & | GetName () const
| Returns the name for this family.
const Labels | GetConstantLabels () const
| Returns the constant labels for this family.
std::vector< MetricFamily > | Collect () const override
| Returns the current value of each dimensional data.

## Detailed Description

template<typename T>
class prometheus::Family< T >

A metric of type T with a set of labeled dimensions.

One of Prometheus main feature is a multi-dimensional data model with time series data identified by metric name and key/value pairs, also known as labels. A time series is a series of data points indexed (or listed or graphed) in time order (https://en.wikipedia.org/wiki/Time_series).

An instance of this class is exposed as multiple time series during scrape, i.e., one time series for each set of labels provided to Add().

For example it is possible to collect data for a metric `http_requests_total`, with two time series:

- all HTTP requests that used the method POST
- all HTTP requests that used the method GET

The metric name specifies the general feature of a system that is measured, e.g., `http_requests_total`. Labels enable Prometheus's dimensional data model: any given combination of labels for the same metric name identifies a particular dimensional instantiation of that metric. For example a label for 'all HTTP requests that used the method POST' can be assigned with `method= "POST"`.

Given a metric name and a set of labels, time series are frequently identified using this notation:

    <metric name> { < label name >= <label value>, ... }

It is required to follow the syntax of metric names and labels given by: https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels

The following metric and label conventions are not required for using Prometheus, but can serve as both a style-guide and a collection of best practices: https://prometheus.io/docs/practices/naming/

Template Parameters

  T | One of the metric types Counter, Gauge, Histogram or Summary.

## Constructor & Destructor Documentation

## Family()

template<typename T >

prometheus::Family< T >::Family | ( | const std::string & | name,
|  | const std::string & | help,
|  | const Labels & | constant_labels
| ) |  |

Create a new metric.

Every metric is uniquely identified by its name and a set of key-value pairs, also known as labels. Prometheus's query language allows filtering and aggregation based on metric name and these labels.

This example selects all time series that have the `http_requests_total` metric name:

    http_requests_total

It is possible to assign labels to the metric name. These labels are propagated to each dimensional data added with Add(). For example if a label `job= "prometheus"` is provided to this constructor, it is possible to filter this time series with Prometheus's query language by appending a set of labels to match in curly braces ({})

    http_requests_total{job= "prometheus"}

For further information see: [Quering Basics] (https://prometheus.io/docs/prometheus/latest/querying/basics/)

Parameters

  name | Set the metric name.
  help | Set an additional description.
  constant_labels | Assign a set of key-value pairs (= labels) to the metric. All these labels are propagated to each time series within the metric.

Exceptions

  std::runtime_exception | on invalid metric or label names.

## Member Function Documentation

## Add()

template<typename T >
template<typename... Args>

T & prometheus::Family< T >::Add | ( | const Labels & | labels,
|  | Args &&... | args
| ) |  |

inline

Add a new dimensional data.

Each new set of labels adds a new dimensional data and is exposed in Prometheus as a time series. It is possible to filter the time series with Prometheus's query language by appending a set of labels to match in curly braces ({})

    http_requests_total{job= "prometheus",method= "POST"}

Parameters

  labels | Assign a set of key-value pairs (= labels) to the dimensional data. The function does nothing, if the same set of labels already exists.
  args | Arguments are passed to the constructor of metric type T. See Counter, Gauge, Histogram or Summary for required constructor arguments.

Returns
  Return the newly created dimensional data or - if a same set of labels already exists - the already existing dimensional data.

Exceptions

  std::runtime_exception | on invalid label names.

## Collect()

template<typename T >

std::vector< MetricFamily > prometheus::Family< T >::Collect | ( |  | ) | const

override virtual

Returns the current value of each dimensional data.

Collect is called by the Registry when collecting metrics.

Returns
  Zero or more samples for each dimensional data.

Implements prometheus::Collectable.

## GetConstantLabels()

template<typename T >

const Labels prometheus::Family< T >::GetConstantLabels | ( |  | ) | const

Returns the constant labels for this family.

Returns
  All constant labels as key-value pairs.

## GetName()

template<typename T >

const std::string & prometheus::Family< T >::GetName | ( |  | ) | const

Returns the name for this family.

Returns
  The family name.

## Has()

template<typename T >

bool prometheus::Family< T >::Has | ( | const Labels & | labels | ) | const

Returns true if the dimensional data with the given labels exist.

Parameters

  labels | A set of key-value pairs (= labels) of the dimensional data.

## Remove()

template<typename T >

void prometheus::Family< T >::Remove | ( | T * | metric | ) |

Remove the given dimensional data.

Parameters

  metric | Dimensional data to be removed. The function does nothing, if the given metric was not returned by Add().