ts_utils API

Query options:

  • max_num_points: maximum number of points per data serie.

  • fill_value: the value to use for filling empty points. Use 0/0 for nan.

  • min_value: minimum value.

  • max_value: maximum value, use math.huge for unlimited.

  • top: number of top items to return in a “topk” query.

  • calculate_stats: if true, calculate additional stats (like average and 95th percentile).

Query result (returned by ts_utils.query and ts_utils.topk):

  • start: result start time epoch (adjusted to UTC).

  • step: result time step in seconds between consecutive series points.

  • count: number of points for each data series.

  • series: a list of data series. See below for details.

  • statistics: additional statistics. See below for details. Statistics are optional.

  • additional_series: (optional) a list of additional series (e.g. the total series).

Data series:

  • label: series label.

  • data: a unidimensional array of series values.

Query result statistics:

  • total: traffic integral in the specified time range.

  • average average value.

  • min_val_idx: index for the minimum series value.

  • min_val: minimum series value.

  • max_val_idx: index for the maximum series value.

  • max_val: maximum series value.

  • 95th_percentile: the 95th percentile.

Note

All the stats are calculate on the total series. The total series is obtained by taking the sum, point by point, of all the returned series. On topk queries, it also includes the non top series.

Functions

function newSchema(name, options)

Define a new timeseries schema.

Parameters

name – the schema identifier.

Returns

the newly created schema.

function getSchema(name)

Find schema by name.

Parameters

name – the schema identifier.

Returns

a schema object on success, nil on error.

function listActiveDrivers()

Return a list of active timeseries drivers.

Returns

list of driver objects.

function append(schema_name, tags_and_metrics, timestamp)

Append a new data point to the specified timeseries.

Parameters

  • schema_name – the schema identifier.

  • tags_and_metrics – a table with tag->value and metric->value mappings.

  • timestamp – the timestamp associated with the data point.

Returns

true on success, false on error.

function query(schema_name, tags, tstart, tend, options)

Perform a query to extract timeseries data.

Parameters

  • schema_name – the schema identifier.

  • tags – a list of filter tags. All the tags for the given schema must be specified.

  • tstart – lower time for the query.

  • tend – upper time for the query.

  • options – (optional) query options.

Returns

query result on success, nil on error.

function queryTopk(schema_name, tags, tstart, tend, options)

Perform a topk query.

Parameters

  • schema_name – the schema identifier.

  • tags – a list of filter tags. All the tags for the given schema must be specified.

  • tstart – lower time bound for the query.

  • tend – upper time bound for the query.

  • options – (optional) query options.

Returns

query result on success, nil on error.

function listSeries(schema_name, tags_filter, start_time)

List all available timeseries for the specified schema, tags and time.

Parameters

  • schema_name – the schema identifier.

  • tags_filter – a list of filter tags. Tags which are not specified are considered wildcard.

  • start_time – time filter. Only timeseries updated after start_time will be returned.

Returns

a (possibly empty) list of tags values for the matching timeseries on success, nil on error.

function batchListSeries(schema_name, tags_filter, start_time)

Add a listSeries request to the current batch.

Note

Call ts_utils.getBatchedListSeriesResult() to get the batch responses

Parameters

  • schema_name – the schema identifier.

  • tags_filter – a list of filter tags. Tags which are not specified are considered wildcard.

  • start_time – time filter. Only timeseries updated after start_time will be returned.

Returns

nil on error, otherwise a number is returned, indicating the item id into the batch

function getBatchedListSeriesResult()

Completes the current batched requests and returns the results.

Returns

nil on error, otherwise a table item_id -> result is returned. See ts_utils.listSeries() for details.

function exists(schema_name, tags_filter)

Verify timeseries existance.

Parameters

  • schema_name – the schema identifier.

  • tags_filter – a list of filter tags. Tags which are not specified are considered wildcard.

Returns

true if the specified series exist, false otherwise.

function delete (schema_prefix, tags)

Delete timeseries data.

Note

E.g. “iface” schema_prefix matches any schema starting with “iface:”. Empty prefix is allowed and matches all the schemas.

Parameters

  • schema_prefix – a prefix for the schemas.

  • tags – a list of filter tags.

Returns

true if operation was successful, false otherwise.

function deleteOldData(ifid)

Delete old data.

Parameters

ifid – the interface ID to process

Returns

true if operation was successful, false otherwise.

function getPossiblyChangedSchemas()

Get a list of existing schemas which have possibly changed format.

Note

This function should be updated whenever an existng schema is changed

Returns

a table with a list of possibly changed schemas