Developer Interface

FeliConnector

class felicien.FeliConnector(url: str = None, tsdb: str = 'prometheus', options: dict = {})

A connector to a TSDB such as Prometheus or VictoriaMetrics

This is an abstraction class to communicate with a Prometheus API’ compatible TSDB, via HTTP. see official documentation: https://prometheus.io/docs/prometheus/latest/querying/api/ https://docs.victoriametrics.com/url-examples/

Attributes:

• base_url: the URL of the TSDB

• tsdb: the type of TSDB: prometheus, victoriametrics

• _options: the requests options, such as auth or (m)TLS

__init__(url: str = None, tsdb: str = 'prometheus', options: dict = {}) → None

Initializes the instance based the access to a TSDB

Args:

url (str, optional): Base URL of the TSDB.

Defaults to None.

tsdb (str, optional): Type of TSDB. Can be “prometheus”,

“victoriametrics”. Defaults to “prometheus”

options (dict, optional): Options to use with requests, such as

auth, TLS verification, client certificate, headers…

Raises:

ValueError if the url is not valid

ValueError if tsdb is not a valid type

ConnectionError if TSDB API is not reachable

KeyError if a option passed to requests is invalid

delete_timeserie(metric: str) → bool

Delete a timeserie in the TSDB

Args:

metric (str): metric of the timeserie, expressed in PromQL.

Returns:

bool: wether the deletion is completed

Raises:

ConnectionError if query status code is not HTTP/204

get_timeserie(metric: str = None) → FeliTS

Retrieve a timeserie from the TSDB

Args:

metric (str, optional): metric of the timeserie, expressed in

PromQL. Defaults to None.

Returns:

FeliTS: Timeserie of the metric

Raises:

ConnectionError if query status code is not HTTP/200

OverflowError if the result is more than one timeserie

ValueError if the result is empty

TypeError if the result is not a vector (range or instant)

import_timeserie(ts: FeliTS) → bool

Import a timeserie into the TSDB

Args:

ts (FeliTS): the timeserie.

Returns:

bool: wether the import is completed

Raises:

ConnectionError if query status code is not HTTP/200

FeliTS

class felicien.FeliTS(from_prom: dict = None, name: str = None, labels: dict = {}, values: Series = None)

A Timeserie of a Prometheus metric

This is a metric representation as returned by the Prometheus API. It includes the metric definition, and the data as a pandas Series. see official documentation: https://prometheus.io/docs/prometheus/latest/querying/api/#expression-query-result-formats

Attributes:

• name: A string with the name of the metric

• labels: A dict of labels of the metric

• data: A pandas.Series with the timeserie

__init__(from_prom: dict = None, name: str = None, labels: dict = {}, values: Series = None) → None

Initializes the instance based on the data from Prometheus API

Args:

from_prom (dict, optional): Query result data from Prometheus API.

name (str, optional): Name of the metric

labels (dict, optional): Labels of the metric

values (pandas Series, optional): Values and their timestamp of

the timeserie as the Index

Raises:

AttributeError if the metric has no __name__

AttributeError if the metric has no value (or values)

ValueError if the value list is empty

ValueError if a item of the value list hasn’t the right format: [timestamp, metric_value]

AttributeError if neither an output from Prometheus API nor raw data are passed to the constructor

as_dataframe(name: str = '') → DataFrame

self.data representation as a pandas.DataFrame

Args:

name (str, optional): Name of the column for the Serie in the

resulting DataFrame. Defaults to self.name.

Returns:

pandas.DataFrame: The self.data, as a pandas.DataFrame

as_dict(timestamp_format: str = 's') → dict

Object representation as a Dictionary

Args:

timestamp_format (str, optional): Format of the timestamps. Could

be ‘s’ for seconds or ‘ms’ for milliseconds. Defaults to ‘s’.

Returns:

dict: representation of the object

Raises:

ValueError if the timestamp_format argument is not “s” or “ms”

as_prometheus(timestamp_format: str = 's') → str

Object representation based on Prometheus API format

Args:

timestamp_format (str, optional): Format of the timestamps. Could

be ‘s’ for seconds or ‘ms’ for milliseconds. Defaults to ‘s’.

Returns:

str: JSON representation of the object, as you could push it

to Prometheus

property frequency: timedelta

Expose the main frequency in the timeseries. In case there are

multiple frequencies, the most frequent is returned.

Returns:

dt.timedelta: the duration between 2 data points

or None for single value serie

property labels_string: str

The labels as a string, as Prometheus would represent it

Returns:

str: all the labels as a key-value list, separated with commas

longest_continuous_segment(position: str = 'last') → Series

Extract the longest continuous segment, which is the longest

segment of the timeserie respecting the frequency, without any missing point

Args:

position (str, optional): Which longest segment to return, in case

multiple segment exist Defaults to last.

Returns:

pd.Series: the extract of the timeserie

Raises:

ValueError if the position argument is not “first” or “last”

normalize(inplace: bool = False) → Series

Normalize the timeserie, filling missing points with NaN values but making sure the index respect the frequency.

Important: points not aligned on the frequency will be dropped, while

missing points on frequency will be added as NaN

Args:

inplace (bool, optional): Control if the trim should be applied

to the current object, or just get the trimmed timeserie. Defaults to False.

Returns:

pd.Series: The normalized timeserie

Raises:

ValueError if the timeserie has no frequency (such as single point

timeserie)

plot() → None

Plot a timeserie

property size: int

Expose the size to the timeseries

Returns:

int: Size of the timeseries

trim_by_date(boundary: datetime = None, keep: str = 'right', inplace: bool = False) → Series

Trim the timeseries by date

Args:

boundary (dt.datetime, optional): Limit on which triming the

timeserie. Defaults to None.

keep (str, optional): Which part of the timeseries to keep.

Defaults to right.

inplace (bool, optional): Control if the trim should be applied

to the current object, or just get the trimmed timeserie. Defaults to False.

Returns:

pd.Series: The trimmed timeseries

Raises:

ValueError if the keep argument is not “left” or “right”

trim_by_size(boundary: int = 0, keep: str = 'right', inplace: bool = False) → Series

Trim the timeseries by size

Args:

boundary (int, optional): Size of the trimmed timeserie. If the

boundary is 0, keep the whole timeserie. Defaults to 0.

keep (str, optional): Which part of the timeseries to keep.

Defaults to right.

inplace (bool, optional): Control if the trim should be applied

to the current object, or just get the trimmed timeserie. Defaults to False.

Returns:

pd.Series: The trimmed timeseries

Raises:

ValueError if the keep argument is not “left” or “right”