opentsdb-query
v0.0.2
Published
Base class for OpenTSDB metric and TSUID queries.
Downloads
106
Readme
Query
Base class for OpenTSDB metric and TSUID queries.
Install
For use in Node.js,
$ npm install opentsdb-query
For use in the browser, use browserify.
Queries
OpenTSDB permits two query types: metric and tsuid.
Metric queries are general queries which return an indeterministic number of timeseries. OpenTSDB implements metric queries by searching for timeseries matching the metric criteria, e.g., metric name
and tag
.
TSUID queries request a specific timeseries having a unique id. Every timeseries has an assigned unique identifier, which is based on metric name
and any tags
.
The distinctions between the two types are 1) metric queries require a metric name and tsuid queries require a string list of tsuids and 2) tsuid queries do not accept tags. Otherwise, both types have the same methods. The shared methods are implemented via a base query class: Query
.
To create a new Query
instance,
var Query = require( 'opentsdb-query' );
var query = new Query();
The instance is configurable and has the following methods...
query.aggregator( [aggregator] )
This method is a setter/getter. If no aggregator
is provided, returns the query aggregator . The default aggregator is avg
. To set a different aggregator
,
query.aggregator( 'min' );
query.downsample( [downsample] )
This method is a setter/getter. If no downsample
function is provided, returns the configured downsample
function. By default, downsampling is turned off (i.e., set to null
). To specify a downsample
function,
query.downsample( '5s-avg' );
query.rate( [bool] )
This method is a setter/getter. If no boolean flag is provided, returns the flag indicating whether to return the difference between consecutive data values. By default, the flag is false
. To turn on difference calculation,
query.rate( true );
Note that rate calculation requires a set of three options which are accessed using the query.rateOptions()
method.
query.rateOptions( [object] )
This method is a setter/getter. If no configuration object is provided, returns the rate options: counter
, counterMax
, resetValue
. counter
must be a boolean; counterMax
must be numeric or null
; and resetValue
must be numeric.
By default,
var rateOptions = {
"counter": false,
"counterMax": null,
"resetValue": 0
};
Notes
When used as setters, all setter/getter methods are chainable. For example,
var Query = require( 'opentsdb-query' ),
query = new Query();
query
.aggregator( 'sum' )
.downsample( '5m-avg' )
.rate( true )
.rateOptions({
"counter": false,
"counterMax": null,
"resetValue": 0
})
.toString();
Tests
Unit
Unit tests use the Mocha test framework with Chai assertions. To run the tests, execute the following command in the top-level application directory:
$ make test
All new feature development should have corresponding unit tests to validate correct functionality.
Test Coverage
This repository uses Istanbul as its code coverage tool. To generate a test coverage report, execute the following command in the top-level application directory:
$ make test-cov
Istanbul creates a ./reports/coverage
directory. To access an HTML version of the report,
$ make view-cov
License
Copyright
Copyright © 2014. Athan Reines.