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