aioprometheus.collectors module¶

class aioprometheus.collectors.Collector(name: str, doc: str, const_labels: Optional[Dict[str, str]] = None, registry: Optional[aioprometheus.collectors.Registry] = None)¶

Bases: object

Base class for all collectors.

Metric names and labels

Every time series is uniquely identified by its metric name and a set of key-value pairs, also known as labels.

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: all HTTP requests that used the method POST to the /api/tracks handler). The query language allows filtering and aggregation based on these dimensions. Changing any label value, including adding or removing a label, will create a new time series.

Label names may contain ASCII letters, numbers, as well as underscores. They must match the regex [a-zA-Z_][a-zA-Z0-9_]*. Label names beginning with __ are reserved for internal use.

Samples

Samples form the actual time series data. Each sample consists of:

a float64 value

a millisecond-precision timestamp

Notation

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

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

For example, a time series with the metric name api_http_requests_total and the labels method="POST" and handler="/messages" could be written like this:

api_http_requests_total{method="POST", handler="/messages"}

get(labels: Dict[str, str]) → Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]¶

Gets a value in the container.

Handy alias for get_value.

Raises: KeyError if an item with matching labels is not present.

get_all() → List[Tuple[Dict[str, str], Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]]]¶: Returns a list populated with 2-tuples. The first element is a dict of labels and the second element is the value of the metric itself.

get_value(labels: Dict[str, str]) → Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]¶

Gets a value in the container.

Raises: KeyError if an item with matching labels is not present.

kind = 3¶

set_value(labels: Dict[str, str], value: Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]) → None¶: Sets a value in the container

class aioprometheus.collectors.Counter(name: str, doc: str, const_labels: Optional[Dict[str, str]] = None, registry: Optional[aioprometheus.collectors.Registry] = None)¶

Bases: aioprometheus.collectors.Collector

A counter is a cumulative metric that represents a single numerical value that only ever goes up. A counter is typically used to count requests served, tasks completed, errors occurred, etc. Counters should not be used to expose current counts of items whose number can also go down, e.g. the number of currently running coroutines. Use gauges for this use case.

Examples: - Number of requests processed - Number of items that were inserted into a queue - Total amount of data that a system has processed

add(labels: Dict[str, str], value: Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]) → None¶

Add the given value to the counter.

Raises: ValueError if the value is negative. Counters can only increase.

get(labels: Dict[str, str]) → Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]¶

Get the Counter value matching an arbitrary group of labels.

Raises: KeyError if an item with matching labels is not present.

inc(labels: Dict[str, str]) → None¶: Increments the counter by 1.

kind = 0¶

set(labels: Dict[str, str], value: Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]) → None¶: Set the counter to an arbitrary value.

class aioprometheus.collectors.Gauge(name: str, doc: str, const_labels: Optional[Dict[str, str]] = None, registry: Optional[aioprometheus.collectors.Registry] = None)¶

Bases: aioprometheus.collectors.Collector

A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.

Examples of Gauges include: - Inprogress requests - Number of items in a queue - Free memory - Total memory - Temperature

Gauges can go both up and down.

add(labels: Dict[str, str], value: Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]) → None¶

Add the given value to the Gauge.

The value can be negative, resulting in a decrease of the gauge.

dec(labels: Dict[str, str]) → None¶: Decrement the gauge by 1.

get(labels: Dict[str, str]) → Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]¶

Get the gauge value matching an arbitrary group of labels.

Raises: KeyError if an item with matching labels is not present.

inc(labels: Dict[str, str]) → None¶: Increments the gauge by 1.

kind = 1¶

set(labels: Dict[str, str], value: Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]) → None¶: Set the gauge to an arbitrary value.

sub(labels: Dict[str, str], value: Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]) → None¶

Subtract the given value from the Gauge.

The value can be negative, resulting in an increase of the gauge.

class aioprometheus.collectors.Histogram(name: str, doc: str, const_labels: Optional[Dict[str, str]] = None, registry: Optional[aioprometheus.collectors.Registry] = None, buckets: Sequence[float] = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, inf))¶

Bases: aioprometheus.collectors.Collector

A histogram samples observations (usually things like request durations or response sizes) and counts them in configurable buckets. It also provides a sum of all observed values.

A histogram with a base metric name of <basename> exposes multiple time series during a scrape:

cumulative counters for the observation buckets, exposed as <basename>_bucket{le=”<upper inclusive bound>”}

the total sum of all observed values, exposed as <basename>_sum

the count of events that have been observed, exposed as <basename>_count (identical to <basename>_bucket{le=”+Inf”} above)

Example use cases: - Response latency - Request size

COUNT_KEY = 'count'¶

DEFAULT_BUCKETS = (0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, inf)¶

REPR_STR = 'histogram'¶

SUM_KEY = 'sum'¶

add(labels: Dict[str, str], value: Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]) → None¶: Add a single observation to the histogram

get(labels: Dict[str, str]) → Dict[Union[float, str], Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]]¶

Get a dict of values, containing the sum, count and buckets, matching an arbitrary group of labels.

Raises: KeyError if an item with matching labels is not present.

kind = 4¶

observe(labels: Dict[str, str], value: Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]) → None¶: Add a single observation to the histogram

class aioprometheus.collectors.MetricsTypes(value)¶

Bases: enum.Enum

An enumeration.

counter = 0¶

gauge = 1¶

histogram = 4¶

summary = 2¶

untyped = 3¶

class aioprometheus.collectors.Registry¶

Bases: object

This class implements a container to hold metrics collectors.

Collectors in the registry must comply with the Collector interface which means that they inherit from the base Collector object and implement a no-argument method called ‘get_all’ that returns a list of Metric instance objects.

clear()¶

Clear all registered collectors.

This function is mainly of use in tests to reset the default registry which may be used in multiple tests.

deregister(name: str) → None¶

Deregister a collector.

This will stop the collector metrics from being emitted.

Parameters: name – The name of the collector to deregister.
Raises: KeyError if collector is not already registered.

get(name: str) → aioprometheus.collectors.Collector¶

Get a collector by name.

Parameters: name – The name of the collector to fetch.
Raises: KeyError if collector is not found.

get_all() → List[aioprometheus.collectors.Collector]¶: Return a list of all collectors

register(collector: aioprometheus.collectors.Collector) → None¶

Register a collector into the container.

The registry provides a container that can be used to access all metrics when exposing them into a specific format.

Parameters: collector – A collector to register in the registry.
Raises: TypeError if collector is not an instance of Collector.
Raises: ValueError if collector is already registered.

class aioprometheus.collectors.Summary(name: str, doc: str, const_labels: Optional[Dict[str, str]] = None, registry: Optional[aioprometheus.collectors.Registry] = None, invariants: Sequence[Tuple[float, float]] = ((0.5, 0.05), (0.9, 0.01), (0.99, 0.001)))¶

Bases: aioprometheus.collectors.Collector

A Summary metric captures individual observations from an event or sample stream and summarizes them in a manner similar to traditional summary statistics:

sum of observations,
observation count,
rank estimations.

Example use cases for Summaries: - Response latency - Request size

COUNT_KEY = 'count'¶

DEFAULT_INVARIANTS = ((0.5, 0.05), (0.9, 0.01), (0.99, 0.001))¶

REPR_STR = 'summary'¶

SUM_KEY = 'sum'¶

add(labels: Dict[str, str], value: Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]) → None¶: Add a single observation to the summary

get(labels: Dict[str, str]) → Dict[Union[float, str], Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]]¶

Get a dict of values, containing the sum, count and quantiles, matching an arbitrary group of labels.

Raises: KeyError if an item with matching labels is not present.

kind = 2¶

observe(labels: Dict[str, str], value: Union[int, float, aioprometheus.histogram.Histogram, quantile.Estimator]) → None¶: Add a single observation to the summary

aioprometheus.collectors.get_registry() → aioprometheus.collectors.Registry¶: Return the default Registry