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

continuous_segment(position: str = 'last', longest: bool = False) → Series

Extract continuous segment from the timeserie respecting the

frequency, without any missing point. This segment can be the longest, or any length, but it has to be eother the first segment or the last from the timeserie.

Args:

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

multiple segment exist Defaults to last.

longest (bool, optional): Should the segment be the longest

Defaults to False.

Returns:

pd.Series: the extract of the timeserie

Raises:

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

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

DEPRECATED: use continuous_segment function instead

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”