I’ve recently pushed version 0.5.2 of datavstime which extends the proxy adapter to support DvT “functions” and “aggregation functions”. There is also a new github project - datavstime-examples - which provides examples of data sources that can be used with this adapter. Currently there are two - a (minimal) example written in go, and a more complex (but less comprehensive) example written in C#. You can also take a look at the ngx_data_vs_time repo which provides another example in the form of an nginx module written in C (but this is only recommended if you are both a masochist and performance freak). A python example is also planned soon.

To provide data to DvT via the proxy adapter, you need to implement 5 HTTP end points, each providing data in JSON format:

/api/v1/predefined-pages
/api/v1/label-and-value-summary
/api/v1/functions
/api/v1/aggregation-functions
/api/v1/series

A brief overview of each of these is provided below. For more detail, have a look a the examples mentioned above. Better docs are on the todo list!

/api/v1/predefined-pages

This endpoint allows you to specify a list of predefined custom pages that will be automatically presented to all users who connect to your data source.

To define a page, it is easiest to design it in the datavstime UI and export it’s JSON representation using the global settings export tab. The predefined-pages endpoint should return a list of such page definitions.

Note: The page definition format is still unstable. You may be required to re-generate / re-export your page definitions for compatibility with future versions of DvT.

/api/v1/label-and-value-summary

Provides a JSON representation of the data presented in the Labels panel. It is queried once only when a user first connects to the data source.

/api/v1/functions

Provides a list of functions that can be applied to a given series in the DvT user interface. The /api/v1/query endpoint should recognise and handle each of these functions.

/api/v1/aggregation-functions

Provides a list of all functions that can be applied in the DvT user interface to aggregate a group of series. The /api/v1/query endpoint should recognise and handle each of these functions.

/api/v1/series

This endpoint provides:

  1. The identity of each series produced by a specified query.
  2. (optionally) data associated with each of these series over a specified time span.

You must pass a valid query in the query parameter, for example:

/api/v1/series?query={metric:'cpu_count'}

You may optionally specify a time span over which data is required using the start, stop and step parameters. For example:

/api/v1/series?query={metric:'cpu_count'}&start=1448848452000&stop=1448848484000&step=1000

The units of start, stop and step are all milliseconds. In the case of start and stop, this is relative to 1970-1-1 00:00:00.

Query format

The query format is inspired by Prometheus. The most basic query is just a collection of label/value pairs. For example:

{metric:'cpu_count',region:'US'}

The set of series selected by this query is the intersection of the sets that would be selected by each key/value pair separately.

One difference between the notation used by DvT and prometheus is that the symbols “:” and “’” are used in place of ‘=’ and ‘”’. I made this change because “:” and “’” do not need to be escaped in URLs (though Chrome does escape the “’” character anyway), whereas ‘=’ and ‘”’ do.

DvT does not require an implementation of more advanced time series selectors, though you are free to implement this if you want (and can specify them in the manual query entry box).

Surrounding the series set specification there can be none, one or both of:

  1. a function to apply to every series in the selected set.
  2. a function to aggregate together all series in the selected set.

For example:

rate({metric:'cpu_count'}[5m])
sum({metric:'cpu_count'})
sum(rate({metric:'cpu_count'}[5m]))

You only need to handle parsing of functions if the list returned by the /api/v1/functions endpoint is not empty and you only need to handle parsing of aggregation functions if the list returned by /api/v1/aggregation-functions is not empty.

Functions

DvT will only ever apply a function directly to series selected by the label/value series selector. All functions known to DvT (i.e. that have been specified via the /api/v1/functions endpoint) must take a single argument. This is specified within square brackets immediately following the series selector.

Aggregation Functions

DvT may apply an aggregation function to series selected by the label/value series selector, or to these series which have been first modified by a function.

… this post is a work in progress. Currently itching to do some development …