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