aioprometheus package

Submodules

aioprometheus.collectors module

class aioprometheus.collectors.Collector(name: str, doc: str, const_labels: Dict[str, str] = 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: Dict[str, str] = 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: Dict[str, str] = 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: Dict[str, str] = 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

Bases: enum.Enum

An enumeration.

counter = 0
gauge = 1
histogram = 4
summary = 2
untyped = 3
class aioprometheus.collectors.Summary(name: str, doc: str, const_labels: Dict[str, str] = 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:

  1. sum of observations,
  2. observation count,
  3. 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.decorators module

This module provides some convenience decorators for metrics

aioprometheus.decorators.count_exceptions(metric: aioprometheus.collectors.Counter, labels: Dict[str, str] = None) → Callable[..., Any]

This decorator provides a convenient way to track count exceptions generated in a callable.

This decorator function wraps a function with code to track how many exceptions occur.

Parameters:
  • metric – a metric to increment when an exception is caught. The metric object being updated is expected to be a Counter metric object.
  • labels – a dict of extra labels to associate with the metric.
Returns:

a coroutine function that wraps the decortated function
aioprometheus.decorators.inprogress(metric: aioprometheus.collectors.Gauge, labels: Dict[str, str] = None) → Callable[..., Any]

This decorator provides a convenient way to track in-progress requests (or other things) in a callable.

This decorator function wraps a function with code to track how many of the measured items are in progress.

The metric is incremented before calling the wrapped function and decremented when the wrapped function is complete.

Parameters:
  • metric – a metric to increment and decrement. The metric object being updated is expected to be a Gauge metric object.
  • labels – a dict of extra labels to associate with the metric.
Returns:

a coroutine function that wraps the decortated function
aioprometheus.decorators.timer(metric: aioprometheus.collectors.Summary, labels: Dict[str, str] = None) → Callable[..., Any]

This decorator provides a convenient way to time a callable.

This decorator function wraps a function with code to calculate how long the wrapped function takes to execute and updates the metric with the duration.

Parameters:
  • metric – a metric to update with the calculated function duration. The metric object being updated is expected to be a Summary metric object.
  • labels – a dict of extra labels to associate with the metric.
Returns:

a coroutine function that wraps the decortated function

aioprometheus.histogram module

class aioprometheus.histogram.Histogram(*buckets)

Bases: object

A Histogram counts individual observations from an event into configurable buckets. This histogram implementation also provides a sum and count of observations.

observe(value: Union[float, int]) → None

Observe the given amount.

Observing a value into the histogram will cumulatively increment the count of observations for the buckets that the observed values falls within. It also adds the value to the sum of all observations.

Parameters:value – A metric value to add to the histogram.
aioprometheus.histogram.exponentialBuckets(start: Union[float, int], factor: Union[float, int], count: int) → List[float]

Returns buckets that are spaced exponentially.

Returns count buckets, where the lowest bucket has an upper bound of start and each following bucket’s upper bound is factor times the previous bucket’s upper bound. There is no +Inf bucket is included in the returned list.

Raises:Exception if count is 0 or negative.
Raises:Exception if start is 0 or negative,
Raises:Exception if factor is less than or equal 1.
aioprometheus.histogram.linearBuckets(start: Union[float, int], width: Union[int, float], count: int) → List[float]

Returns buckets that are spaced linearly.

Returns count buckets, each width wide, where the lowest bucket has an upper bound of start. There is no +Inf bucket is included in the returned list.

Raises:Exception if count is zero or negative.

aioprometheus.metricdict module

class aioprometheus.metricdict.MetricDict(*args, **kwargs)

Bases: collections.abc.MutableMapping

MetricDict stores the data based on the labels so we need to generate custom hash keys based on the labels

EMPTY_KEY = '__EMPTY__'

aioprometheus.negotiator module

aioprometheus.negotiator.negotiate(accepts_headers: Sequence[str]) → Callable[bool, aioprometheus.formats.base.IFormatter]

Negotiate a response format by scanning through a list of ACCEPTS headers and selecting the most efficient format.

The formatter returned by this function is used to render a response.

Parameters:accepts_headers – a list of ACCEPT headers fields extracted from a request.
Returns:a formatter class to form up the response into the appropriate representation.
aioprometheus.negotiator.parse_accepts(accept_headers: Sequence[str]) → Set[str]

Return a sequence of accepts items in the request headers

aioprometheus.pusher module

class aioprometheus.pusher.Pusher(job_name: str, addr: str, loop: asyncio.base_events.BaseEventLoop = None)

Bases: object

This class can be used in applications that can’t support the standard pull strategy. The pusher object pushes the metrics to a push-gateway which can be scraped by Prometheus.

PATH = '/metrics/job/{0}'
add(registry: aioprometheus.registry.CollectorRegistry) → aiohttp.web_response.Response

add works like replace, but only metrics with the same name as the newly pushed metrics are replaced.

delete(registry: aioprometheus.registry.CollectorRegistry) → aiohttp.web_response.Response

delete deletes metrics from the push gateway. All metrics with the grouping key specified in the URL are deleted.

replace(registry: aioprometheus.registry.CollectorRegistry) → aiohttp.web_response.Response

replace pushes new values for a group of metrics to the push gateway.

Note

All existing metrics with the same grouping key specified in the URL will be replaced with the new metrics value.

aioprometheus.registry module

class aioprometheus.registry.CollectorRegistry

Bases: object

This class implements the metrics collector registry.

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.

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) → Union[aioprometheus.collectors.Counter, aioprometheus.collectors.Gauge, aioprometheus.collectors.Histogram, aioprometheus.collectors.Summary]

Get a collector by name.

Parameters:name – The name of the collector to fetch.
Raises:KeyError if collector is not found.
get_all() → List[Union[aioprometheus.collectors.Counter, aioprometheus.collectors.Gauge, aioprometheus.collectors.Histogram, aioprometheus.collectors.Summary]]

Return a list of all collectors

register(collector: Union[aioprometheus.collectors.Counter, aioprometheus.collectors.Gauge, aioprometheus.collectors.Histogram, aioprometheus.collectors.Summary]) → None

Register a collector.

This will allow the collector metrics to be emitted.

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.
aioprometheus.registry.Registry

alias of aioprometheus.registry.CollectorRegistry

aioprometheus.renderer module

aioprometheus.renderer.render(registry: aioprometheus.registry.CollectorRegistry, accepts_headers: Sequence[str]) → Tuple[bytes, dict]

Render the metrics in this registry to a specific format.

The format chosen is determined by scanning through the ACCEPTS headers and selecting the most efficient format. If no accepts headers information is provided then Text format is used as the default.

Parameters:
  • registry – A collector registry that contains the metrics to be rendered into a specific format.
  • accepts_headers – a list of ACCEPT headers fields extracted from a request.
Returns:

a 2-tuple where the first item is a bytes object that represents the formatted metrics and the second item is a dict of header fields that can be added to a HTTP response.

aioprometheus.service module

This module implements an asynchronous Prometheus metrics service.

class aioprometheus.service.Service(registry: aioprometheus.registry.CollectorRegistry = None, loop: asyncio.base_events.BaseEventLoop = None)

Bases: object

This class implements a Prometheus metrics service that can be embedded within asyncio based applications so they can be scraped by the Prometheus.io server.

accepts(request: aiohttp.web_request.Request) → Set[str]

Return a sequence of accepts items in the request headers

base_url

Return the base service url

Raises:Exception if the server has not been started.
Returns:the base service URL as a string
deregister(name: str) → None

Deregister a collector.

Parameters:name – A collector name to deregister.
handle_metrics(request: aiohttp.web_request.Request) → aiohttp.web_response.Response

Handle a request to the metrics route.

The request is inspected and the most efficient response data format is chosen.

handle_robots(request: aiohttp.web_request.Request) → aiohttp.web_response.Response

Handle a request to /robots.txt

If a robot ever stumbles on this server, discourage it from indexing.

handle_root(request: aiohttp.web_request.Request) → aiohttp.web_response.Response

Handle a request to the / route.

Serves a trivial page with a link to the metrics. Use this if ever you need to point a health check at your the service.

metrics_url

Return the Prometheus metrics url

Raises:Exception if the server has not been started.
Returns:the metrics URL as a string
register(collector: Union[aioprometheus.collectors.Counter, aioprometheus.collectors.Gauge, aioprometheus.collectors.Histogram, aioprometheus.collectors.Summary]) → None

Register a collector.

Raises:TypeError if collector is not an instance of Collector.
Raises:ValueError if collector is already registered.
root_url

Return the root service url

Raises:Exception if the server has not been started.
Returns:the root URL as a string
start(addr: str = '', port: int = 0, ssl: ssl.SSLContext = None, metrics_url: str = '/metrics') → None

Start the prometheus metrics HTTP(S) server.

Parameters:
  • addr – the address to bind the server on. By default this is set to an empty string so that the service becomes available on all interfaces.
  • port – The port to bind the server on. The default value is 0 which will cause the server to bind to an ephemeral port. If you want the server to operate on a fixed port then you need to specifiy the port.
  • ssl – a sslContext for use with TLS.
  • metrics_url – The name of the endpoint route to expose prometheus metrics on. Defaults to ‘/metrics’.
Raises:

Exception if the server could not be started.
stop(wait_duration: float = 1.0) → None

Stop the prometheus metrics HTTP(S) server.

Parameters:wait_duration – the number of seconds to wait for connections to finish.

Module contents