1.3. 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.
  • 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 exists(schema_name, tags_filter)

A shortcut for ts_utils.listSeries to 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