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.

Return
the newly created schema.
Parameters
  • name: the schema identifier.

function getSchema(name)

Find schema by name.

Return
a schema object on success, nil on error.
Parameters
  • name: the schema identifier.

function listActiveDrivers()

Return a list of active timeseries drivers.

Return
list of driver objects.

function append(schema_name, tags_and_metrics, timestamp)

Append a new data point to the specified timeseries.

Return
true on success, false on error.
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.

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

Perform a query to extract timeseries data.

Return
query result on success, nil on error.
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.

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

Perform a topk query.

Return
query result on success, nil on error.
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.

function listSeries(schema_name, tags_filter, start_time)

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

Return
a (possibly empty) list of tags values for the matching timeseries on success, nil on error.
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.

function batchListSeries(schema_name, tags_filter, start_time)

Add a listSeries request to the current batch.

Return
nil on error, otherwise a number is returned, indicating the item id into the 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.

function getBatchedListSeriesResult()

Completes the current batched requests and returns the results.

Return
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.

Return
true if the specified series exist, false otherwise.
Parameters
  • schema_name: the schema identifier.
  • tags_filter: a list of filter tags. Tags which are not specified are considered wildcard.

function delete(schema_prefix, tags)

Delete timeseries data.

Return
true if operation was successful, false otherwise.
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.

function deleteOldData(ifid)

Delete old data.

Return
true if operation was successful, false otherwise.
Parameters
  • ifid: the interface ID to process

function getPossiblyChangedSchemas()

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

Return
a table with a list of possibly changed schemas
Note
This function should be updated whenever an existng schema is changed