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.

    • oldest_data_datetime=datetime.datetime(2019,5,23,12,0), will delete any data that is older than “23 May 2019 12:00:00”

    • 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(*args, **kwargs)[source]

Plot a very simple line graph for the metric time-series.

show(block=None)[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: Retry = None, auth: tuple = None, proxy: dict = None, session: Session = None, timeout: int = None, method: str = 'GET')[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

  • auth – (optional) Auth tuple to enable Basic/Digest/Custom HTTP Auth. See python requests library auth parameter for further explanation.

  • proxy – (Optional) Proxies dictionary to enable connection through proxy. Example: {“http_proxy”: “<ip_address/hostname:port>”, “https_proxy”: “<ip_address/hostname:port>”}

  • session – (Optional) Custom requests.Session to enable complex HTTP configuration

  • timeout – (Optional) A timeout (in seconds) applied to all requests

  • method – (Optional) (str) HTTP Method (GET or POST) to use for Query APIs that allow POST (/query, /query_range and /labels). Use POST for large and complex queries. Default is GET.

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

check_prometheus_connection(params: dict = None) → bool[source]

Check Promethus connection.

Parameters:

params – (dict) Optional dictionary containing parameters to be sent along with the API request.

Returns:

(bool) True if the endpoint can be reached, False if cannot be reached.

close() → None[source]

Close the underlying HTTP session and release connection-pool resources.

custom_query(query: str, params: dict = None, timeout: int = 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 PromQL query examples

  • params – (dict) Optional dictionary containing GET parameters to be sent along with the API request, such as “time”

  • timeout – (Optional) A timeout (in seconds) applied to the request

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, end_time: datetime, step: str, params: dict = None, timeout: int = 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 PromQL query 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”

  • timeout – (Optional) A timeout (in seconds) applied to the request

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_label_names(params: dict = None)[source]

Get a list of all labels.

Parameters:

params – (dict) Optional dictionary containing GET parameters to be sent along with the API request, such as “start”, “end” or “match[]”.

Returns:

(list) A list of labels 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

get_label_values(label_name: str, params: dict = None)[source]

Get a list of all values for the label.

Parameters:

  • label_name – (str) The name of the label for which you want to get all the values.

  • params – (dict) Optional dictionary containing GET parameters to be sent along with the API request, such as “time”

Returns:

(list) A list of names for the label 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

get_metric_aggregation(query: str, operations: list, start_time: datetime = None, end_time: 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 PromQL query examples

  • operations – (list) A list of operations to perform on the values. Operations are specified in string type.

  • 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” 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_metadata(metric: str, limit: int = None, limit_per_metric: int = None)[source]

Get metadata about metrics.

Parameters:

  • metric – (str) Optional metric name to filter metadata

  • limit – (int) Optional maximum number of metrics to return

  • limit_per_metric – (int) Optional maximum number of metadata entries per metric

Returns:

(dict) A dictionary mapping metric names to lists of metadata entries in format: {‘metric_name’: [{‘type’: str, ‘help’: str, ‘unit’: str}, …]}

Raises:

(RequestException) Raises an exception in case of a connection error (PrometheusApiClientException) Raises in case of non 200 response status code

get_metric_range_data(metric_name: str, label_config: dict = None, start_time: datetime = datetime.datetime(2026, 4, 13, 4, 3, 55, 685564), end_time: datetime = datetime.datetime(2026, 4, 13, 4, 13, 55, 685573), chunk_size: 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

get_scrape_pools() → list[str][source]

Get a list of all scrape pools in activeTargets.

get_series(start: datetime, end: datetime, params: dict = None)[source]

Get a list series happening between start and end times.

Parameters:

  • start – (int) Start time unix ts

  • end – (int) End time unix ts

  • params – (dict) Optional dictionary containing GET parameters to be sent along with the API request, such as “start”, “end” or “match[]”.

Returns:

(list) A list of labels 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

get_target_metadata(target: dict[str, str], metric: str = None)[source]

Get metadata about metrics from a specific target.

Parameters:

  • target – (dict) A dictionary containing target labels to match against (e.g. {‘job’: ‘prometheus’})

  • metric – (str) Optional metric name to filter metadata

Returns:

(list) A list of metadata entries for matching targets

Raises:

(RequestException) Raises an exception in case of a connection error (PrometheusApiClientException) Raises in case of non 200 response status code

get_targets(state: str = None, scrape_pool: str = None)[source]

Get a list of all targets from Prometheus.

Parameters:

  • state – (str) Optional filter for target state (‘active’, ‘dropped’, ‘any’). If None, returns both active and dropped targets.

  • scrape_pool – (str) Optional filter by scrape pool name

Returns:

(dict) A dictionary containing active and dropped targets

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.MetricValueConversionError[source]

Bases: Exception

Raises when we find a metric that is a string where we fail to convert it to a float.

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, index: ExtensionArray | ndarray | Index | Series | SequenceNotStr | range | None = None, columns: ExtensionArray | ndarray | Index | Series | SequenceNotStr | range | None = None, dtype: ExtensionDtype | str | dtype | type[str | complex | bool | object] | None = None, copy: bool = False, ts_values_keep: str = 'last', ts_as_datetime: bool = True)[source]

Bases: 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

  • 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.

  • 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’.

  • ts_as_datetime – (bool) default True. Convert the timestamps returned by prometheus from float64 (unix time) to pandas datetime objects. This results in the timestamp column of the returned dataframe to be of dtype datetime64[ns] instead float64

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: ExtensionArray | ndarray | Index | Series | SequenceNotStr | range | None = None, columns: ExtensionArray | ndarray | Index | Series | SequenceNotStr | range | None = None, dtype: ExtensionDtype | str | dtype | type[str | complex | bool | object] | None = None, copy: bool = False, ts_as_datetime: bool = True)[source]

Bases: 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.

  • ts_as_datetime – (bool) default True. Convert the timestamps returned by prometheus from float64 (unix time) to pandas datetime objects. This results in a pd.DatetimeIndex as the dtype of the index of the returned dataframe, instead of pd.Float64Index

Example Usage:
prom = PrometheusConnect()
metric_data = prom.get_metric_range_data(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.