/atsd-api-nodejs

Axibase Time Series Database API Client for Node.js

Primary LanguageJavaScript

ATSD Node.js Client

CircleCI Code Climate codecov

Table of Contents

Overview

ATSD Node.js Client enables developers to interact with Axibase Time Series Database through both Data and Meta APIs.

Implemented Methods

ATSD Client

ATSDClient is the client base class. Create ATSDClient instance using ATSDClient(options) where options is an object:

Key Description Required
url Full ATSD URL with port. Yes
user Username. Yes
password Password. Yes
strictSSL Require SSL certificate validation. No.
Default setting: true.

ATSDClient contains the asynchronous method request:

ATSDClient.request(method, path, params, payload, callback)

Additionally, ATSDClient contains separate methods for each type of request:

ATSDClient.getRequest(path, params, payload, callback)
ATSDClient.postRequest(path, params, payload, callback)
ATSDClient.putRequest(path, params, payload, callback)
ATSDClient.patchRequest(path, params, payload, callback)
ATSDClient.deleteRequest(path, params, payload, callback)

Arguments are enumerated below:

Argument Type Description
method String Request method: GET, POST, PUT, PATCH, or DELETE.
path String Path added to base ATSD API URL.
For example: metrics is appended as follows, atsd_server/api/v1/metrics.
params Object URL query string parameters.
payload Object JSON request payload.
callback Function(error, response, body) Callback function.

Entities, Metrics, Properties, Alerts, and Series are all subclasses of ATSDClient and use the same constructor.

REST API

The REST API allows you to insert and retrieve data from the database using HTTP requests.

Series

  • Series: query
    Retrieves time series objects for the specified metric, entity, tags, and date range. Applies common time series transformations including aggregation, interpolation, downsampling etc.

  • Series: insert
    Inserts a timestamped array of numbers for a given series identified by metric, entity, and series tags.

Properties

Messages

Alerts

Meta API

The Meta API allows you to query metadata for metrics, entities, and entity groups in the database.

Metrics

Entities

  • Entity: get
    Retrieves fields and tags describing the specified entity.

  • Entity: update
    Updates fields and tags of the specified entity.

  • Entity: create or replace
    Creates an entity with specified fields and tags or replaces the fields and tags of an existing entity.

  • Entity: delete
    Deletes the specified entity and removes the entity from any entity groups it belongs to.

  • Entity: metrics
    Retrieves a list of metrics collected by the entity.

Entity Groups

Additional Functions

There are a number of convenience functions dedicated to making certain requests easier to execute. Unlike the functions above, these functions do not replicate the signatures of ATSD API methods.

Client function Equivalent Invocation Note
Series.query(args, callback) Series.get(payload, callback) with payload being {'queries': [args]} timeFormat for response is set to iso; instead of {'series': [...]} returns [...].
Series.queryDetail(metric, entity, tags, startTime, endTime, callback) Series.query(args, callback) with args as an object consisting of metric, entity etc. startTime and endTime can be a timestamp in milliseconds, a string (ATSD API startDate and endDate), or a Date object.
Series.queryStatistic(metric, entity, tags, startTime, endTime, statistic, period, callback) Same as above. Same as above.
Series.insertData(metric, entity, tags, data, callback) Series.insert(payload, callback) with payload being [inserts] where inserts is an object consisting of metric, entity etc.

For statistics and units used to aggregate the data through series queries, corresponding enumerations exist for Series class:

  • Series.statistic
  • Series.unit

Installing Node.js Client

Install ATSD Node.js Client with npm:

npm install --save atsd-api

Setup

var atsd_api = require('atsd-api');

var options = {
  url: '...',
  user: '...',
  password: '...'
};

var entities   = new atsd_api.Entities(options);
var metrics    = new atsd_api.Metrics(options);
var series     = new atsd_api.Series(options);
var properties = new atsd_api.Properties(options);
var alerts     = new atsd_api.Alerts(options);

Examples

Series:

// inserting series data without versions
series.insertData('temperature', 'sensor001', {}, [
    {'d': '2015-11-23T08:19:00.000Z', 'v': 51},
    {'d': '2015-11-23T08:20:00.000Z', 'v': 52}
  ], function(error_insert, response, _) {
    if (!error_insert) {
      console.log('Insert: ' + response.statusCode);
    }
  }
);
> Insert: 200
// inserting series data with versions
series.insertData('temperature', 'sensor001', {}, [
    {'d': '2015-11-23T08:21:00.000Z', 'v': 50, 'version': {'status': 'provisional', 'source': 'gateway-1'}}
  ], function(error_insert, response, _) {
    if (!error_insert) {
      console.log('Insert with versions: ' + response.statusCode);
    }
  }
);
> Insert with versions: 200
// retrieving data without versions
series.queryDetail(
  'temperature', 'sensor001', {},
  'current_day', 'next_day',
  function(error_detail, _, body) {
    if (!error_detail) {
      console.log('Detail: ' + JSON.stringify(body));
    }
  }
);
> Detail: [{"entity":"sensor001","metric":"temperature1","tags":{},"type":"HISTORY","aggregate":{"type":"DETAIL"},"data":[{"d":"2015-11-23T08:19:00.000Z","v":51},{"d":"2015-11-23T08:20:00.000Z","v":52},{"d":"2015-11-23T08:21:00.000Z","v":50}]}]
// retrieving data with versions
series.query({
    'metric': 'temperature',
    'entity': 'sensor001',
    'startDate': 'current_day',
    'endDate': 'next_day',
    'versioned': true
  }, function(error_detail, _, body) {
    if (!error_detail) {
      console.log('Detail with versions: ' + JSON.stringify(body));
    }
  }
);
> Detail with versions: [{"entity":"sensor001","metric":"temperature1","tags":{},"type":"HISTORY","aggregate":{"type":"DETAIL"},"data":[{"d":"2015-11-23T08:19:00.000Z","v":51},{"d":"2015-11-23T08:20:00.000Z","v":52},{"d":"2015-11-23T08:21:00.000Z","v":50,"version":{"source":"gateway-1","status":"provisional"}}]}]
// retrieving yesterday's data averaged by 6 hours
series.queryStatistic(
  'cpu_busy', 'nurswgvml007', {},
  'previous_day', 'current_day',
  Series.statistic.AVG, {'count': 6, 'unit': Series.unit.HOUR},
  function(error, _, body) {
    if (!error) {
      console.log('Average: ' + JSON.stringify(body));
    }
  }
);
> Average: [{"entity":"nurswgvml007","metric":"cpu_busy","tags":{},"type":"HISTORY","aggregate":{"type":"AVG","period":{"count":6,"unit":"HOUR"}},"data":[{"d":"2015-11-22T00:00:00.000Z","v":18.35364243323441},{"d":"2015-11-22T06:00:00.000Z","v":14.058392592592591},{"d":"2015-11-22T12:00:00.000Z","v":13.460140845070423},{"d":"2015-11-22T18:00:00.000Z","v":13.851594955489615}]}]

Alerts:

// updating alerts 'evt-1' and 'evt-2'
alerts.update(
  [
    {
      'action': 'update',
      'fields': {
        'acknowledge': true
      },
      'alerts': [
        {'id': 'evt-1'},
        {'id': 'evt-2'}
      ]
    }
  ],
  function(error, response, _) {
    if (!error) {
      console.log('Update: ' + response.statusCode);
    }
  }
);
> Update: 200

Properties:

// getting property types of entity 'atsd'
entities.getPropertyTypes('atsd', {}, function (error, _, body) {
  if (!error) {
    console.log('Property types: ' + JSON.stringify(body));
  }
});
> Property types: ["jfs","system","disk","cpu","java_method","configuration","network"]
// inserting a property
properties.insert(
  [
    {
      'type':'type-1',
      'entity':'entity-1',
      'key':{'server_name':'server','user_name':'system'},
      'tags':{'name-1': 'value-1'}
    }
  ],
  function(error_insert, response, _) {
    if (!error_insert) {
      console.log('Insert: ' + response.statusCode);

      // retrieving the same property
      properties.getByEntityAndType(
        'entity-1', 'type-1', {},
        function (error_get, _, body) {
          if (!error_get) {
            console.log('Properties by entity and type: ' + JSON.stringify(body));
          }
        }
      );
    }
  }
);
> Insert: 200
> Properties by entity and type: [{"type":"type-1","entity":"entity-1","key":{"server_name":"server","user_name":"system"},"tags":{"name-1":"value-1","name.1":"value-1"},"timestamp":1448122917843}]

Series Dump:

entities.getAll({}, function (error_entities, _, body_entities) {
  if (!error_entities) {
    // choosing the first entity
    var entity = body_entities[0]['name'];

    console.log('First entity: ' + entity);

    // retrieving all metrics for that entity
    metrics.getByEntity(entity, {}, function (error_metrics, _, body_metrics) {
      if (!error_metrics) {
        // choosing the first metric
        var metric = body_metrics[0]['name'];

        console.log('First metric: ' + metric);

        // getting data for the chosen entity and metric
        series.queryDetail(
          metric, entity, {},
          'current_hour', 'current_hour + 10 * second',
          function (error_series, _, body_series) {
            if (!error_series) {
              var data = body_series[0]['data'];

              console.log('Data: ' + JSON.stringify(data));
            }
          }
        );
      }
    })
  }
});
> First entity: atsd
> First metric: actions_per_minute
> Data: [{"d":"2015-11-21T14:00:02.497Z","v":0}]