statscloud.io-client v2.2.26

statscloud.io client for node.js

Installation

npm install --save statscloud.io-client

Usage

Make sure you configured StatsCloud via .statscloud.json configuration file. Read https://medium.com/@roman.kisilenko/software-application-monitoring-how-to-or-how-not-to-let-your-production-fail-9481dd0ef6de for configuration options.

// import module
let statscloud = require('statscloud.io-client');

// optionally, specify environment and/or tags
statscloud.withEnvironment('staging').withTags('us-west-2', 'my-server');

// start the module, returns a promise
statscloud.start()
  .then(() => {...})
  .catch(err => console.log(err));

// track events
statscloud.recordEvent('statistic', 123);
statscloud.recordEvents({name: 'gauge', measurement: 123}, {name: 'counter'});

// stop the module (useful for tests)
statscloud.stop()

Creating multiple clients

You can also create multiple clients with custom config files:

let statscloud = require('statscloud.io-client');

// create default client
statscloud.withEnvironment('staging').withTags('us-west-2', 'my-server');
statscloud.start()
  .then(() => {...})
  .catch(err => console.log(err));

// create custom client
// tags and environment will be copied from default client
let businessClient = statscloud.cloneWithConfigFile('.business.statscloud.json');

// also you can change tags and environment for custom client
businessClient.withEnvironment('production').withTags('other-server');

// and start as usual
businessClient.start()
  .then(() => {...})
  .catch(err => console.log(err));

// track events
statscloud.recordEvent('statistic', 123);
statscloud.recordEvents({name: 'gauge', measurement: 123}, {name: 'counter'});
businessClient.recordEvent('business-metric', 123);

Specify token in environment variable

If token is not specified in .statscloud.json configuration file, then it will be retrieved from STATSCLOUD_AUTH_TOKEN environment variable.

Command Line Interface

You can use command line interface of statscloud client:

> statscloud deploy
Cluster deployed sucessfully

You can specify environment and tags using command line arguments. Use statscloud --help to get more information.

AWS Lambda support

AWS Lambda support is provided via a plugin. You can find AWS Lambda sample code here. Documentation for AWS Lambda plugin can be found here.

StatsCloud provides a wrapper for Lambda functions which manages StatsCloud client and processes built-in metrics.

"aws-lambda" plugin must be enabled in configuration.

const statscloud = require('statscloud.io-client/lambda');

// async-style handler
module.exports.exampleAsync = statscloud.lambda(async (event, context) => {
  return await Promise.resolve({
    message: 'StatsCloud async example',
    input: event
  });
});

// callback-style handler
module.exports.exampleCallback = statscloud.lambda((event, context, callback) => {
  callback(null, {
    message: 'StatsCloud callback example',
    input: event
  });
});

// context-style handler
module.exports.exampleContext = statscloud.lambda((event, context) => {
  context.succeed({
    message: 'StatsCloud context example',
    input: event
  });
});

Selecting transport

You can select transport to use. By default websocket over HTTPS (ws) transport is used. Websocket transport adds a few round trip times to execution time. If you have a lambda function which must execute in millisecond time, we recommend you to switch to UDP (udp) transport. UDP transport does not add any delay to lambda execution time but is not secure.

withTransport method can be used to select transport. You can call withTransport on statscloud to set global value or set withTransport on lambda to set transport for specific lambda function.

// import module
let statscloud = require('statscloud.io-client/lambda');

// configure udp transport by default
statscloud.withTransport('udp');

// configure ws transport for specific lambda function
module.exports.exampleAsync = statscloud.lambda(async (event, context) => {
  return await Promise.resolve({
    message: 'StatsCloud async example',
    input: event
  });
}).withTransport('ws');

Recovery-agent

Make sure you configured Recovery-agent via .statscloud.json configuration file. Example

{
  "token": "your-auth-token",
  "application": "your-app-name", 
  "environment": "your-app-environment"
}

Running recovery agent on Linux server

To use recovery agent you must install statscloud package and then use statscloud-recovery-agent CLI to install and uninstall recovery agent service on your Linux server.

You can list all recovery agent CLI options using statscloud-recovery-agent --help shell command.

Running recovery agent on other systems (e.g. in docker image)

To launch recovery agent on other systems you need to make sure that recovery.js node.js application is running to perform failure recovery operations.

Recovery agent example.

Please add this code to recovery.js file which can be located in a subdirectory of the project root. The .statscloud.json configuration file should be located in the root of your project.

// import module
let agent = require('statscloud.io-client').recoveryAgent;

// add failture listner
agent.onFailure('failure').recoverAs(callback);
agent.onFailure('failure').recoverAs(agent.shellScript("your-script"));

// start recovery-agent
agent.start()
.catch(error => {
	console.log(error);
});