TempoDB Python API Client

The TempoDB Python API Client makes calls to the TempoDB API. The module is available on PyPi as tempodb.

1. Install tempodb

pip install tempodb

1. After installing tempodb, download tempodb-write-demo.py.

2. Edit your-api-key and your-api-secret in tempodb-write-demo.py.

3. Run tempodb-write-demo.py to insert 10 days of test data.

python tempodb-write-demo.py

1. Download tempodb-read-demo.py

2. Edit your-api-key and your-api-secret in tempodb-read-demo.py.

3. Run tempodb-read-demo.py to read back the data you just wrote in.

python tempodb-read-demo.py

Classes

Client(key, secret, host="api.tempo-db.com", port=443, secure=True, pool_connections=10, pool_maxsize=10)

Stores the session information for authenticating and accessing TempoDB. Your api key and secret is required. The Client also allows you to specify the hostname, port, and protocol (http or https). This is used if you are on a private cluster. The default hostname and port should work for the standard cluster.

All access to data is made through a client instance.

Members

• key - api key (string)
• secret - api secret (string)
• host - hostname for the cluster (string)
• port - port for the cluster (int)
• secure - protocol to use (True=https, False=http)
• pool_connections - default connection poolsize
• pool_maxsize - maximum number of connections to open within the pool

DataPoint(ts, value)

Represents one timestamp/value pair.

Members

• ts - timestamp (datetime)
• value - the datapoint's value (double, long, boolean)

Series(id, key, name="", attributes={}, tags=[])

Represents metadata associated with the series. Each series has a globally unique id that is generated by the system and a user defined key. The key must be unique among all of your series. Each series may have a set of tags and attributes that can be used to filter series during bulk reads. Attributes are key/value pairs. Both the key and attribute must be strings. Tags are keys with no values. Tags must also be strings.

Members

• id - unique series id (string)
• key - user defined key (string)
• name - human readable name for the series (string)
• attributes - key/value pairs providing metadata for the series (dictionary - keys and values are strings)
• tags - (list of strings)

DataSet(series, start, end, data=[], summary=None)

Represents data from a time range of a series. This is essentially a list of DataPoints with some added metadata. This is the object returned from a query. The DataSet contains series metadata, the start/end times for the queried range, a list of the DataPoints and a statistics summary table. The Summary table contains statistics for the time range (sum, mean, min, max, count, etc.)

Members

• series - series metadata (Series)
• start - start time for the queried range (datetime)
• end - end time for the queried range (datetime)
• data - datapoints (list of DataPoints)
• summary - a summary table of statistics for the queried range (Summary)

DeleteSummary(deleted)

Represents data associated with a delete operation. This is similar to what you would get back when executing a SQL UPDATE or DELETE query that returns the number of rows affected.

Members

• deleted - the number of series that were successfully deleted

Client API

create_series(key=None)

Creates and returns a series object, optionally with the given key.

Parameters

• key - key for the series (string)

Returns

The newly created Series object

Example

The following example creates two series, one with a given key of "my-custom-key", one with a randomly generated key.

from tempodb import Client

client = Client("api-key", "api-secret")

series1 = client.create_series('my-custom-key')
series2 = client.create_series()

get_series(ids=[], keys=[], tags=[], attributes={})

Gets a list of series objects, optionally filtered by the provided parameters. Series can be filtered by id, key, tag and attribute.

Parameters

• ids - a list of ids to include (list of strings)
• keys - a list of keys to include (list of strings)
• tags - a list of tags to filter on. These tags are and'd together (list of strings)
• attributes - a dictionary of key/value pairs to filter on. These attributes are and'd together. (dictionary)

Returns

A list of Series objects

Example

The following example returns all series with tags "tag1" and "tag2" and attribute "attr1" equal to "value1".

from tempodb import Client

client = Client("api-key", "api-secret")

tags = ["tag1", "tag2"]
attributes = {
    "attr1": "value1"
}

series_list = client.get_series(tags=tags, attributes=attributes)

update_series(series)

Updates a series. The series id is taken from the passed-in series object. Currently, only tags and attributes can be modified. The easiest way to use this method is through a read-modify-write cycle.

Parameters

• series - the new series (Series)

Returns

The updated Series

Example

The following example reads the list of series with key test1 (should only be one) and replaces the tags with tag3.

from tempodb import Client

client = Client("api-key", "api-secret")

keys = ["test1"]
series_list = client.get_series(keys=keys)

if series_list:
    series = series_list[0]
    series.tags = ["tag3"]
    client.update_series(series)

delete_series(ids=[], keys=[], tags=[], attributes={}, allow_truncation=False)

Delete series objects by the given criteria. This method has the same query parameters as get_series. Series can be deleted by id, key, tag and attribute. Calling this method with no filter arguments will delete all series in a given database (Similar to 'DELETE * FROM series' in sql)

Parameters

• ids - a list of ids to include (List of strings)
• keys - a list of keys to include (List of strings)
• tags - a list of tags to filter on. These tags are and'd together (List of strings)
• attributes - a dict of key/value pairs to filter on. These attributes are and'd together. (Dict)
• allow_truncation - a boolean that must be passed when you wish to delete all your series. Mutually exclusive with the filter query parameters. (Boolean)

Returns

A DeleteSummary object

Example

The following example deletes all series with "tag1" and "tag2" and attribute "attr1" equal to "value1".

from tempodb import Client

client = Client("api-key", "api-secret")

tags = ["tag1", "tag2"]
attributes = {
	"attr1": "value1"
}

summary = client.delete_series(tags=tags, attributes=attributes)

read(start, end, interval="", function="", ids=[], keys=[], tags=[], attributes={}, tz="")

Gets a list of DataSets for the specified start/end times. The interval parameter allows you to specify a rollup period. For example, "1hour" will roll the data up on the hour using the provided function. The function parameter specifies the folding function to use while rolling the data up. A rollup is selected automatically if no interval or function is given. The auto rollup interval is calculated by the total time range (end - start) as follows:

• range <= 2 days - raw data is returned
• range <= 30 days - data is rolled up on the hour
• else - data is rolled up by the day

Rollup intervals are specified by a number and a time period. For example, 1day or 5min. Supported time periods:

• min
• hour
• day
• month
• year

Supported rollup functions:

• sum
• max
• min
• avg or mean
• stddev (standard deviation)
• count

You can also retrieve raw data by specifying "raw" as the interval. The series to query can be filtered using the remaining parameters.

Parameters

• start - start time for the query (datetime)
• end - end time for the query (datetime)
• interval - the rollup interval (string)
• function - the rollup folding function (string)
• ids - a list of ids to include (list of strings)
• keys - a list of keys to include (list of strings)
• tags - a list of tags to filter on. These tags are and'd together (list of strings)
• attributes - a dictionary of key/value pairs to filter on. These attributes are and'd together. (dictionary)
• tz - the time zone of the output data points (string)

Returns

A list of DataSets

Example

The following example returns a list of series from 2012-01-01 to 2012-01-02 for the series with key "my-custom-key", with the maximum value for each hour.

import datetime
from tempodb import Client

client = Client("api-key", "api-secret")

start = datetime.datetime(2012, 1, 1)
end = datetime.datetime(2012, 1, 2)
keys = ["my-custom-key",]

data = client.read(start, end, keys=keys, interval="1hour", function="max")

read_id(series_id, start, end, interval="", function="", tz="")

Gets a DataSet by series id. The id, start, and end times are required. The same rollup rules apply as for the multi series read (above).

Parameters

• series_id - id for the series to read from (string)
• start - start time for the query (datetime)
• end - end time for the query (datetime)
• interval - the rollup interval (string)
• function - the rollup folding function (string)
• tz - the time zone of the output data points (string)

Returns

A DataSet

Example

The following example reads data for the series with id "38268c3b231f1266a392931e15e99231" from 2012-01-01 to 2012-02-01 and returns a minimum datapoint per day.

import datetime
from tempodb import Client

client = Client("api-key", "api-secret")

start = datetime.datetime(2012, 1, 1)
end = datetime.datetime(2012, 2, 1)

data = client.read_id("38268c3b231f1266a392931e15e99231", start, end, interval="1day", function="min")

read_key(series_key, start, end, interval="", function="", tz="")

Gets a DataSet by series key. The key, start, and end times are required. The same rollup rules apply as for the multi series read (above).

Parameters

• series_key - key for the series to read from (string)
• start - start time for the query (datetime)
• end - end time for the query (datetime)
• interval - the rollup interval (string)
• function - the rollup folding function (string)
• tz - the time zone of the output data points (string)

Returns

A DataSet

Example

The following example reads data for the series with key "my-custom-key" from 2012-01-01 to 2012-02-01 and returns a minimum datapoint per day.

import datetime
from tempodb import Client

client = Client("api-key", "api-secret")

start = datetime.datetime(2012, 1, 1)
end = datetime.datetime(2012, 2, 1)

data = client.read_key("my-custom-key", start, end, interval="1day", function="min")

write_id(series_id, data)

Writes datapoints to the specified series. The series id and a list of DataPoints are required.

Parameters

• series_id - id for the series to write to (string)
• data - the data to write (list of DataPoints)

Returns

Nothing

Example

The following example write three datapoints to the series with id "38268c3b231f1266a392931e15e99231".

from datetime import datetime
from tempodb import Client, DataPoint

client = Client("api-key", "api-secret")

data = [
    DataPoint(datetime(2012, 1, 1, 1, 0, 0), 12.34),
    DataPoint(datetime(2012, 1, 1, 1, 1, 0), 1.874),
    DataPoint(datetime(2012, 1, 1, 1, 2, 0), 21.52),
]

client.write_id("38268c3b231f1266a392931e15e99231", data)

write_key(series_key, data)

Writes datapoints to the specified series. The series key and a list of DataPoints are required. Note: a series will be created if the provided key does not exist.

Parameters

• series_key - key for the series to write to (string)
• data - the data to write (list of DataPoints)

Returns

Nothing

Example

The following example write three datapoints to the series with key "my-custom-key".

from datetime import datetime
from tempodb import Client, DataPoint

client = Client("api-key", "api-secret")

data = [
    DataPoint(datetime(2012, 1, 1, 1, 0, 0), 12.34),
    DataPoint(datetime(2012, 1, 1, 1, 1, 0), 1.874),
    DataPoint(datetime(2012, 1, 1, 1, 2, 0), 21.52),
]

client.write_key("my-custom-key", data)

write_bulk(ts, data)

Writes values to multiple series for a particular timestamp. This function takes a timestamp and a parameter called data, which is a list of dictionaries containing the series id or key and the value. For example:

data = [
    { 'id': '01868c1a2aaf416ea6cd8edd65e7a4b8', 'v': 4.164 },
    { 'id': '38268c3b231f1266a392931e15e99231', 'v': 73.13 },
    { 'key': 'your-custom-key', 'v': 55.423 },
    { 'key': 'foo', 'v': 324.991 },
]

Parameters

• ts - the timestamp for the datapoints
• data - a list of dictionaries containing an id or key and the value

Returns

Nothing

Example

The following example writes datapoints to four separate series at the same timestamp.

import datetime
from tempodb import Client

client = Client("api-key", "api-secret")

ts = datetime.datetime(2012, 1, 8, 1, 21)
data = [
    { 'id': '01868c1a2aaf416ea6cd8edd65e7a4b8', 'v': 4.164 },
    { 'id': '38268c3b231f1266a392931e15e99231', 'v': 73.13 },
    { 'key': 'your-custom-key', 'v': 55.423 },
    { 'key': 'foo', 'v': 324.991 },
]

client.write_bulk(ts, data)

write_multi(data)

Write datapoints to multiple series for multiple timestamps. This function takes an List of dictionaries containing the timestamp, either the series id or series key, and the value. For example:

data = [
    { 't': datetime.datetime(2013, 8, 21), 'id': '01868c1a2aaf416ea6cd8edd65e7a4b8', 'v': 4.164 },
    { 't': datetime.datetime(2013, 8, 22), 'id': '38268c3b231f1266a392931e15e99231', 'v': 73.13 },
    { 't': datetime.datetime(2013, 8, 23), 'key': 'your-custom-key', 'v': 55.423 },
    { 't': datetime.datetime(2013, 8, 24), 'key': 'foo', 'v': 324.991 },
]

Parameters

• data - the data to write (List of {t, id, v} or {t, key, v} dictionaries)

Returns

The return body is either empty on success (response code will be 200) or contains a error dictionary with a list of response objects in event of a single or multi-point failure (response code will be 207). Each response object contains a status code and an list of error messages. This list has a one to one correspondence with the original list. For example if you submitted this list:

data = [
    { 't': datetime.datetime(2013, 8, 21), 'v': 4.164 },
    { 't': datetime.datetime(2013, 8, 22), 'id': '38268c3b231f1266a392931e15e99231', 'v': 134.3},
    {}
]

You would recieve this 207 response body:

{'error':
  {"multistatus": [
    { "status": "422", "messages": [ "Must provide a series ID or key" ] },
    { "status": "200", "messages": [] },
    { "status": "422", "messages": [ "Must provide a numeric value", "Must provide a series ID or key" ] }
]}}

Example

The following example writes datapoints to four separate series to 4 different timestamps.

import datetime
from tempodb import Client

client = Client("api-key", "api-secret")
data = [
    { 't': datetime.datetime(2013, 8, 21), 'id': '01868c1a2aaf416ea6cd8edd65e7a4b8', 'v': 4.164 },
    { 't': datetime.datetime(2013, 8, 22), 'id': '38268c3b231f1266a392931e15e99231', 'v': 73.13 },
    { 't': datetime.datetime(2013, 8, 23), 'key': 'your-custom-key', 'v': 55.423 },
    { 't': datetime.datetime(2013, 8, 24), 'key': 'foo', 'v': 324.991 },
]

client.write_multi(data)

increment_id(series_id, data)

Increments the value of the specified series at the given timestamp. The value of the datapoint is the amount to increment. This is similar to a write. However the value is incremented by the datapoint value instead of overwritten. Values are incremented atomically, so this is useful for counting events. The series id and a list of DataPoints are required.

Parameters

• series_id - id for the series to increment (string)
• data - the data to write (list of DataPoints)

Returns

Nothing

Example

The following example increments three datapoints of the series with id "38268c3b231f1266a392931e15e99231".

from datetime import datetime
from tempodb import Client, DataPoint

client = Client("api-key", "api-secret")

data = [
    DataPoint(datetime(2012, 1, 1, 1, 0, 0), 1),
    DataPoint(datetime(2012, 1, 1, 1, 1, 0), 2),
    DataPoint(datetime(2012, 1, 1, 1, 2, 0), 1),
]

client.increment_id("38268c3b231f1266a392931e15e99231", data)

increment_key(series_key, data)

Increments the value of the specified series at the given timestamp. The value of the datapoint is the amount to increment. This is similar to a write. However, the value is incremented by the datapoint value instead of overwritten. Values are incremented atomically, so this is useful for counting events. The series key and an array of DataPoints are required. Note: a series will be created if the provided key does not exist.

Parameters

• series_key - key for the series to increment (string)
• data - the data to write (list of DataPoints)

Returns

Nothing

Example

The following example increments three datapoints of the series with key "my-custom-key".

from datetime import datetime
from tempodb import Client, DataPoint

client = Client("api-key", "api-secret")

data = [
    DataPoint(datetime(2012, 1, 1, 1, 0, 0), 12.34),
    DataPoint(datetime(2012, 1, 1, 1, 1, 0), 1.874),
    DataPoint(datetime(2012, 1, 1, 1, 2, 0), 21.52),
]

client.increment_key("my-custom-key", data)

increment_bulk(ts, data)

Increments values to multiple series for a particular timestamp. This function takes a timestamp and a parameter called data, which is a list of dictionaries containing the series id or key and the value. For example:

data = [
    { 'id': '01868c1a2aaf416ea6cd8edd65e7a4b8', 'v': 4 },
    { 'id': '38268c3b231f1266a392931e15e99231', 'v': 2 },
    { 'key': 'your-custom-key', 'v': 1 },
    { 'key': 'foo', 'v': 1 },
]

Parameters

• ts - the timestamp for the datapoints
• data - a list of dictionaries containing an id or key and the value

Returns

Nothing

Example

The following example increments datapoints of four separate series at the same timestamp.

import datetime
from tempodb import Client

client = Client("api-key", "api-secret")

ts = datetime.datetime(2012, 1, 8, 1, 21)
data = [
    { 'id': '01868c1a2aaf416ea6cd8edd65e7a4b8', 'v': 4 },
    { 'id': '38268c3b231f1266a392931e15e99231', 'v': 2 },
    { 'key': 'your-custom-key', 'v': 1 },
    { 'key': 'foo', 'v': 1 },
]

client.increment_bulk(ts, data)

increment_multi(data)

increment datapoints to multiple series for multiple timestamps. This function takes an List of dictionaries containing the timestamp, either the series id or series key, and the value. For example:

data = [
    { 't': datetime.datetime(2013, 8, 21), 'id': '01868c1a2aaf416ea6cd8edd65e7a4b8', 'v': 46 },
    { 't': datetime.datetime(2013, 8, 22), 'id': '38268c3b231f1266a392931e15e99231', 'v': 7 },
    { 't': datetime.datetime(2013, 8, 23), 'key': 'your-custom-key', 'v': 55 },
    { 't': datetime.datetime(2013, 8, 24), 'key': 'foo', 'v': 1 },
]

Parameters

• data - the data to increment (List of {t, id, v} or {t, key, v} dictionaries)

Returns

The return body is either empty on success (response code will be 200) or contains a error dictionary with a list of response objects in event of a single or multi-point failure (response code will be 207). Each response object contains a status code and an list of error messages. This list has a one to one correspondence with the original list. For example if you submitted this list:

data = [
    { 't': datetime.datetime(2013, 8, 21), 'v': 4 },
    { 't': datetime.datetime(2013, 8, 22), 'id': '38268c3b231f1266a392931e15e99231'},
    {}
]

You would recieve this 207 response body:

{'error':
  {"multistatus": [
    { "status": "422", "messages": [ "Must provide a series ID or key" ] },
    { "status": "200", "messages": [] },
    { "status": "422", "messages": [ "Must provide a numeric value", "Must provide a series ID or key" ] }
]}}

Example

The following example increments datapoints to four separate series to 4 different timestamps.

import datetime
from tempodb import Client

client = Client("api-key", "api-secret")
data = [
    { 't': datetime.datetime(2013, 8, 21), 'id': '01868c1a2aaf416ea6cd8edd65e7a4b8', 'v': 46 },
    { 't': datetime.datetime(2013, 8, 22), 'id': '38268c3b231f1266a392931e15e99231', 'v': 7 },
    { 't': datetime.datetime(2013, 8, 23), 'key': 'your-custom-key', 'v': 55 },
    { 't': datetime.datetime(2013, 8, 24), 'key': 'foo', 'v': 1 },
]

client.increment_multi(data)

delete_id(series_id, start, end)

Deletes a range of data specified by series id. The id, start, and end times are required. As with the read api, the start datetime is inclusive and the end datetime is exclusive. i.e. [start, end)

Parameters

• series_id - id for the series to delete from (string)
• start - start time for the query (datetime, inclusive)
• end - end time for the query (datetime, exclusive)

Returns

Nothing

Example

The following example deletes data for the series with id "38268c3b231f1266a392931e15e99231" from 2012-01-01 to 2012-02-01.

import datetime
from tempodb import Client

client = Client("api-key", "api-secret")

start = datetime.datetime(2012, 1, 1)
end = datetime.datetime(2012, 2, 1)

response = client.delete_id("38268c3b231f1266a392931e15e99231", start, end)

delete_key(series_key, start, end)

Deletes a range of data from a series referenced by series key. The key, start, and end times are required. As with the read api, the start datetime is inclusive and end datetime is exclusive. i.e. [start, end)

Parameters

• series_key - key for the series to delete from (string)
• start - start time for the query (datetime)
• end - end time for the query (datetime)

Returns

Nothing

Example

The following example deletes data for the series with key "my-custom-key" from 2012-01-01 to 2012-02-01.

import datetime
from tempodb import Client

client = Client("api-key", "api-secret")

start = datetime.datetime(2012, 1, 1)
end = datetime.datetime(2012, 2, 1)

response = client.delete_key("my-custom-key", start, end)