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.

Parameters:

options – global options.

Returns:

the newly created driver.

function append(schema, timestamp, tags, metrics)

Append a new data point to the timeseries.

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.

Returns:

the true on success, false otherwise.

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

Query timeseries data.

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.

Returns:

a (possibly empty) query result on success, nil on failure.

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

Calculate a sum on the timeseries metrics.

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.

Returns:

a table containing metric->metric_total mappings on success, nil on failure.

function listSeries(schema, tags_filter, wildcard_tags, start_time, end_time)

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

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.

Returns:

a (possibly empty) list of tags values for the matching timeseries on success, nil for non-existing series.

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

Get top k items information.

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.

Returns:

a (possibly empty) topk result on success, nil on error.

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.

Parameters:

ifid – can be used to possibly provide a more accurate answer.

Returns:

most recent timestamp available.

function delete (schema_prefix, tags)

Delete timeseries data.

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.

Returns:

true if operation was successful, false otherwise.

function deleteOldData(ifid)

Delete old data.

Parameters:

ifid – the interface ID to process

Returns:

true if operation was successful, false otherwise.

function setup(ts_utils)

This is called when some driver configuration changes.

Parameters:

ts_utils – a reference to the ts_utils module

Returns:

true if operation was successful, false otherwise.