Class CirconusData

This module provides simplified methods for data fetching operations. To gain access to the full functionality use the circonusapi module.

Example

from circonusapi import circonusdata

# Option A: Connect to the Circonus API using a token
circ = circonusdata.from_api(api_token)

# Option B: Connect to IRONdb instance
# circ = circonusdata.from_irondb("http://irondb1.dev.net:8112", account=27)

# Run a CAQL query
from datetime import datetime
circ.caql('''

  1 + 2 | label("A")

''', datetime(2020,1,1), 60, 10)

# Result
#
# {
#   'version': 'DF4',
#    'head': {'count': 10, 'start': 1577836800, 'period': 60},
#    'meta': [{'kind': 'numeric', 'label': 'A'}],
#    'data': [[3, 3, 3, 3, 3, 3, 3, 3, 3, 3]]
# }

# Fetch CAQL as DataFrame
circ.caqldf('''

    find("duration", limit=10) | label("%tv{__check_target}")

''', datetime(2020, 1, 1), 60, 60 * 4)

# Result
#
#                      xkcd.com  xkcd.com  151.101.64.67  k8sdemo2
# 2020-01-01 00:00:00         3         3              3        49
# 2020-01-01 00:01:00         3         3              3        55
# 2020-01-01 00:02:00         3         3              3        61
# 2020-01-01 00:03:00         3         3              3        48

More examples can be found in the ./examples folder in this repository.

class circonusapi.circonusdata.CirconusData(token=None, endpoint=None, account=1)

Circonus data fetching class.

Direct constructor calls should be avoided. Use the provided factory methods .from_api() / .from_irondb() to create instances of this class.

caql(query, start, period, count, convert_hists=True, explain=False)

Fetch data using CAQL.

Args:

  • query (str): the CAQL query string

  • start (int/datetime): starttime of the query. Either UNIX timestamp in seconds or datetime object

  • period (int): period of data to fetch

  • count (int): number of datapoints to fetch

  • convert_hists (boolean, optional): Convert returned histograms to Circllhist objects. Requires Circllhist to be available.

Returns:

res (dict): result in DF4 format. Example:

{
  "head" : { count = 60, start = ..., period = 60 }
  "meta" : [ {kind:"numeric", label:"some_metric"}, {...}, ... ] -- per metric metadata
  "data" : [ [1,1,1,1,...], [2,2,2,2,...] ] -- per metric data
}
caqldf(*args, **kwargs)

Fetch CAQL as pandas DataFrame with …

  • Columns : output metrics

  • Column names : metric labels

  • Row index : timestamps

classmethod from_api(token)

Connect to the Circonus API with a token

Args:

token (str): Circonus API token

classmethod from_irondb(endpoint, account=1)

Connect to an IRONdb node, instead of a CirconusAPI endpoint

Args:

  • endpoint (str): IRONdb node URL, in the form “<protocol>://<hostname/ip>:<port>”, e.g. “http://localhost:8112”

  • account (int): account id to use for CAQL requests.

Notes:

The current implementation will issue all requests against a single node.