opentsdb-query

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

MIT license.

---

Copyright

Copyright © 2014. Athan Reines.