prometheus_api_client package¶

Submodules¶

prometheus_api_client.metric module¶

A Class for metric object.

class prometheus_api_client.metric.Metric(metric, oldest_data_datetime=None)[source]¶

Bases: object

A Class for Metric object.

Parameters:

metric – (dict) A metric item from the list of metrics received from prometheus
oldest_data_datetime –
(datetime|timedelta) Any metric values in the dataframe that are older than this value will be deleted when new data is added to the dataframe using the __add__(“+”) operator.
- oldest_data_datetime=datetime.timedelta(days=2), will delete the
metric data that is 2 days older than the latest metric. The dataframe is pruned only when new data is added to it. n * oldest_data_datetime=datetime.datetime(2019,5,23,12,0), will delete any data that is older than “23 May 2019 12:00:00” n * oldest_data_datetime=datetime.datetime.fromtimestamp(1561475156) can also be set using the unix timestamp

Example Usage:

prom = PrometheusConnect()

my_label_config = {'cluster': 'my_cluster_id', 'label_2': 'label_2_value'}

metric_data = prom.get_metric_range_data(metric_name='up', label_config=my_label_config) Here metric_data is a list of metrics received from prometheus

# only for the first item in the list ``my_metric_object = Metric(metric_data[0], datetime.timedelta(days=10)) ``

__add__(other)[source]¶

Overloading operator +.

Add two metric objects for the same time-series

Example Usage:

metric_1 = Metric(metric_data_1)
metric_2 = Metric(metric_data_2)
metric_12 = metric_1 + metric_2 # will add the data in ``metric_2`` to ``metric_1``
                                # so if any other parameters are set in ``metric_1``
                                # will also be set in ``metric_12``
                                # (like ``oldest_data_datetime``)

Returns:	(Metric) Returns a Metric object with the combined metric data

of the two added metrics

Raises:	(TypeError) Raises an exception when two metrics being added are

from different metric time-series

__eq__(other)[source]¶

Overloading operator =.

Check whether two metrics are the same (are the same time-series regardless of their data)

Example Usage:

metric_1 = Metric(metric_data_1)

metric_2 = Metric(metric_data_2)

print(metric_1 == metric_2) # will print True if they belong to the same time-series

Returns:	(bool) If two Metric objects belong to the same time-series, i.e. same name and label config, it will return True, else False

__str__()[source]¶

Make it print in a cleaner way when print function is used on a Metric object.

Example Usage:

metric_1 = Metric(metric_data_1)

print(metric_1) # will print the name, labels and the head of the dataframe

plot()[source]¶: Plot a very simple line graph for the metric time-series.

prometheus_api_client.metrics_list module¶

A list of Metric objects.

class prometheus_api_client.metrics_list.MetricsList(metric_data_list)[source]¶

Bases: list

A Class to initialize a list of Metric objects at once.

Parameters:	metric_data_list – (list\|json) This is an individual metric or list of metrics received from prometheus as a result of a promql query.

Example Usage:

prom = PrometheusConnect()
my_label_config = {'cluster': 'my_cluster_id', 'label_2': 'label_2_value'}
metric_data = prom.get_metric_range_data(metric_name='up', label_config=my_label_config)

metric_object_list = MetricsList(metric_data) # metric_object_list will be initialized as
                                              # a list of Metric objects for all the
                                              # metrics downloaded using get_metric query

prometheus_api_client.prometheus_connect module¶

A Class for collection of metrics from a Prometheus Host.

class prometheus_api_client.prometheus_connect.PrometheusConnect(url: str = 'http://127.0.0.1:9090', headers: dict = None, disable_ssl: bool = False, retry: urllib3.util.retry.Retry = None)[source]¶

Bases: object

A Class for collection of metrics from a Prometheus Host.

Parameters:

url – (str) url for the prometheus host
headers – (dict) A dictionary of http headers to be used to communicate with the host. Example: {“Authorization”: “bearer my_oauth_token_to_the_host”}
disable_ssl – (bool) If set to True, will disable ssl certificate verification for the http requests made to the prometheus host
retry – (Retry) Retry adapter to retry on HTTP errors

all_metrics(params: dict = None)[source]¶

Get the list of all the metrics that the prometheus host scrapes.

Parameters:	params – (dict) Optional dictionary containing GET parameters to be sent along with the API request, such as “time”
Returns:	(list) A list of names of all the metrics available from the specified prometheus host
Raises:	(RequestException) Raises an exception in case of a connection error (PrometheusApiClientException) Raises in case of non 200 response status code

custom_query(query: str, params: dict = None)[source]¶

Send a custom query to a Prometheus Host.

This method takes as input a string which will be sent as a query to the specified Prometheus Host. This query is a PromQL query.

Parameters:	query – (str) This is a PromQL query, a few examples can be found at https://prometheus.io/docs/prometheus/latest/querying/examples/ params – (dict) Optional dictionary containing GET parameters to be sent along with the API request, such as “time”
Returns:	(list) A list of metric data received in response of the query sent
Raises:	(RequestException) Raises an exception in case of a connection error (PrometheusApiClientException) Raises in case of non 200 response status code

custom_query_range(query: str, start_time: datetime.datetime, end_time: datetime.datetime, step: str, params: dict = None)[source]¶

Send a query_range to a Prometheus Host.

This method takes as input a string which will be sent as a query to the specified Prometheus Host. This query is a PromQL query.

Parameters:	query – (str) This is a PromQL query, a few examples can be found at https://prometheus.io/docs/prometheus/latest/querying/examples/ start_time – (datetime) A datetime object that specifies the query range start time. end_time – (datetime) A datetime object that specifies the query range end time. step – (str) Query resolution step width in duration format or float number of seconds params – (dict) Optional dictionary containing GET parameters to be sent along with the API request, such as “timeout”
Returns:	(dict) A dict of metric data received in response of the query sent
Raises:	(RequestException) Raises an exception in case of a connection error (PrometheusApiClientException) Raises in case of non 200 response status code

get_current_metric_value(metric_name: str, label_config: dict = None, params: dict = None)[source]¶

Get the current metric value for the specified metric and label configuration.

Parameters:	metric_name – (str) The name of the metric label_config – (dict) A dictionary that specifies metric labels and their values params – (dict) Optional dictionary containing GET parameters to be sent along with the API request, such as “time”
Returns:	(list) A list of current metric values for the specified metric
Raises:	(RequestException) Raises an exception in case of a connection error (PrometheusApiClientException) Raises in case of non 200 response status code

Example Usage:

prom = PrometheusConnect()

my_label_config = {'cluster': 'my_cluster_id', 'label_2': 'label_2_value'}

prom.get_current_metric_value(metric_name='up', label_config=my_label_config)

get_metric_aggregation(query: str, operations: list, start_time: datetime.datetime = None, end_time: datetime.datetime = None, step: str = '15', params: dict = None)[source]¶

Get aggregations on metric values received from PromQL query.

This method takes as input a string which will be sent as a query to the specified Prometheus Host. This query is a PromQL query. And, a list of operations to perform such as- sum, max, min, deviation, etc. with start_time, end_time and step.

The received query is passed to the custom_query_range method which returns the result of the query and the values are extracted from the result.

Parameters:	query – (str) This is a PromQL query, a few examples can be found

at https://prometheus.io/docs/prometheus/latest/querying/examples/ :param operations: (list) A list of operations to perform on the values. Operations are specified in string type. :param start_time: (datetime) A datetime object that specifies the query range start time. :param end_time: (datetime) A datetime object that specifies the query range end time. :param step: (str) Query resolution step width in duration format or float number of seconds :param params: (dict) Optional dictionary containing GET parameters to be sent along with the API request, such as “timeout” Available operations - sum, max, min, variance, nth percentile, deviation and average.

Returns:	(dict) A dict of aggregated values received in response to the operations

performed on the values for the query sent.

Example output :

{: ‘sum’: 18.05674, ‘max’: 6.009373

}

get_metric_range_data(metric_name: str, label_config: dict = None, start_time: datetime.datetime = datetime.datetime(2020, 11, 17, 17, 38, 22, 784802), end_time: datetime.datetime = datetime.datetime(2020, 11, 17, 17, 48, 22, 784817), chunk_size: datetime.timedelta = None, store_locally: bool = False, params: dict = None)[source]¶

Get the current metric value for the specified metric and label configuration.

Parameters:	metric_name – (str) The name of the metric. label_config – (dict) A dictionary specifying metric labels and their values. start_time – (datetime) A datetime object that specifies the metric range start time. end_time – (datetime) A datetime object that specifies the metric range end time. chunk_size – (timedelta) Duration of metric data downloaded in one request. For example, setting it to timedelta(hours=3) will download 3 hours worth of data in each request made to the prometheus host store_locally – (bool) If set to True, will store data locally at, “./metrics/hostname/metric_date/name_time.json.bz2” params – (dict) Optional dictionary containing GET parameters to be sent along with the API request, such as “time”
Returns:	(list) A list of metric data for the specified metric in the given time range
Raises:	(RequestException) Raises an exception in case of a connection error (PrometheusApiClientException) Raises in case of non 200 response status code

prometheus_api_client.exceptions module¶

Project wide exception classes.

exception prometheus_api_client.exceptions.PrometheusApiClientException[source]¶

Bases: Exception

API client exception, raises when response status code != 200.

prometheus_api_client.metric_snapshot_df module¶

A pandas.DataFrame subclass for Prometheus query response.

class prometheus_api_client.metric_snapshot_df.MetricSnapshotDataFrame(data=None, ts_values_keep: str = 'last', index: Optional[Collection[T_co]] = None, columns: Optional[Collection[T_co]] = None, dtype: Union[ExtensionDtype, str, numpy.dtype, Type[Union[str, float, int, complex, bool]], None] = None, copy: bool = False)[source]¶

Bases: pandas.core.frame.DataFrame

Subclass to format and represent Prometheus query response as pandas.DataFrame.

Assumes response is either a json or sequence of jsons.

This is different than passing raw list of jsons to pandas.DataFrame in that it unpacks metric label values, extracts (first or last) timestamp-value pair (if multiple pairs are retuned), and concats them before passing to the pandas DataFrame constructor.

Some argument descriptions in this docstring were copied from pandas.core.frame.DataFrame.

Parameters:

data – (list|json) A single metric (json with keys “metric” and “values”/”value”) or list of such metrics received from Prometheus as a response to query
ts_values_keep – (str) If several timestamp-value tuples are returned for a given metric + label config, determine which one to keep. Currently only supports ‘first’, ‘last’.
index – (pandas.Index|array-like) Index to use for resulting dataframe. Will default to pandas.RangeIndex if no indexing information part of input data and no index provided.
columns – (pandas.Index|array-like) Column labels to use for resulting dataframe. Will default to list of labels + “timestamp” + “value” if not provided.
dtype – (dtype) default None. Data type to force. Only a single dtype is allowed. If None, infer.
copy – (bool) default False. Copy data from inputs. Only affects DataFrame / 2d ndarray input.

Example Usage:

prom = PrometheusConnect()
metric_data = prom.get_current_metric_value(metric_name='up', label_config=my_label_config)
metric_df = MetricSnapshotDataFrame(metric_data)
metric_df.head()
'''
+-------------------------+-----------------+------------+-------+
| __name__ | cluster      | label_2         | timestamp  | value |
+==========+==============+=================+============+=======+
| up       | cluster_id_0 | label_2_value_2 | 1577836800 | 0     |
+-------------------------+-----------------+------------+-------+
| up       | cluster_id_1 | label_2_value_3 | 1577836800 | 1     |
+-------------------------+-----------------+------------+-------+
'''

prometheus_api_client.metric_range_df module¶

A pandas.DataFrame subclass for Prometheus range vector responses.

class prometheus_api_client.metric_range_df.MetricRangeDataFrame(data=None, index: Optional[Collection[T_co]] = None, columns: Optional[Collection[T_co]] = None, dtype: Union[ExtensionDtype, str, numpy.dtype, Type[Union[str, float, int, complex, bool]], None] = None, copy: bool = False)[source]¶

Bases: pandas.core.frame.DataFrame

Subclass to format and represent Prometheus query response as pandas.DataFrame.

Assumes response is either a json or sequence of jsons.

This class should be used specifically to instantiate a query response, where the query response has several timestamp values per series. That is, a range vector is expected. If the data is an instant vector, use MetricSnapshotDataFrame instead.

Some argument descriptions in this docstring were copied from pandas.core.frame.DataFrame.

Parameters:

data – (list|json) A single metric (json with keys “metric” and “values”/”value”) or list of such metrics received from Prometheus as a response to query
index – (pandas.Index|array-like) Index to use for resulting dataframe. Will default to pandas.RangeIndex if no indexing information part of input data and no index provided.
columns – (pandas.Index|array-like) Column labels to use for resulting dataframe. Will default to list of labels + “timestamp” + “value” if not provided.
dtype – (dtype) default None. Data type to force. Only a single dtype is allowed. If None, infer.
copy – (bool) default False. Copy data from inputs. Only affects DataFrame / 2d ndarray input.

Example Usage:

prom = PrometheusConnect()
metric_data = prom.get_current_metric_value(metric_name='up', label_config=my_label_config)
metric_df = MetricRangeDataFrame(metric_data)
metric_df.head()
'''
+------------+------------+-----------------+--------------------+-------+
|            |  __name__  | cluster         | label_2            | value |
+-------------------------+-----------------+--------------------+-------+
| timestamp  |            |                 |                    |       |
+============+============+=================+====================+=======+
| 1577836800 |   __up__   | cluster_id_0    | label_2_value_2    | 0     |
+-------------------------+-----------------+--------------------+-------+
| 1577836801 |   __up__   | cluster_id_1    | label_2_value_3    | 1     |
+-------------------------+-----------------+------------=-------+-------+
'''

Module contents¶

A collection of tools to collect and manipulate prometheus metrics.