Driver Implementation

Topk result:
  • topk: a sorted list of a topk item
  • statistics: (optional) query result statistics.
  • additional_series: (optional) a list of additional series (e.g. the total series).
Topk item:
  • tags: a map tag_name -> tag_value
  • value: the integral value for the topk item on the specified time range

A timeseries driver must implement the API described below.

Functions

function new(options)

Driver constructor.

Return
the newly created driver.
Parameters
  • options: global options.

function append(schema, timestamp, tags, metrics)

Append a new data point to the timeseries.

Return
the true on success, false otherwise.
Parameters
  • schema: the schema object.
  • timestamp: the data point timestamp.
  • tags: map tag_name->tag_value. It contains exactly the tags defined in the schema.
  • metrics: map metric_name->metric_value. It contains exactly the metrics defined in the schema.

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

Query timeseries data.

Return
a (possibly empty) query result on success, nil on failure.
Parameters
  • schema: the schema object.
  • tstart: lower time bound for the query.
  • tend: upper time bound for the query.
  • tags: a list of filter tags. It contains exactly the tags defined in the schema.
  • options: query options.

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

Calculate a sum on the timeseries metrics.

Return
a table containing metric->metric_total mappings on success, nil on failure.
Parameters
  • schema: the schema object.
  • tstart: lower time bound for the query.
  • tend: upper time bound for the query.
  • tags: a list of filter tags. It contains exactly the tags defined in the schema.
  • options: query options.

function listSeries(schema, tags_filter, wildcard_tags, start_time, end_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 for non-existing series.
Parameters
  • schema: the schema object.
  • tags_filter: a list of filter tags.
  • wildcard_tags: the remaining tags of the schema which are considered wildcard.
  • start_time: time filter. Only timeseries updated after start_time will be returned.
  • end_time: time filter. Only timeseries updated before end_time will be returned.

function topk(schema, tags, tstart, tend, options, top_tags)

Get top k items information.

Return
a (possibly empty) topk result on success, nil on error.
Parameters
  • schema: the schema object.
  • tags: a list of filter tags.
  • tstart: lower time bound for the query.
  • tend: upper time bound for the query.
  • options: query options.
  • top_tags: the remaining tags of the schema, on which top k calculation is taking place.

function export()

Informs the driver that it’s time to export data.

Note
This is called periodically by ntopng and should not be called manually.

function getLatestTimestamp(ifid)

Get the most recent timestamp available for queries.

Note
a conservative way to implement this is to return the current time.
Return
most recent timestamp available.
Parameters
  • ifid: can be used to possibly provide a more accurate answer.

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. When a given scheam tag is not specified, it will be considered wildcard.

function deleteOldData(ifid)

Delete old data.

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

function setup(ts_utils)

This is called when some driver configuration changes.

Return
true if operation was successful, false otherwise.
Parameters
  • ts_utils: a reference to the ts_utils module