khronus v1.0.0

NodeJS client for Khronus

A simple Khronus client for NodeJS applications. This client implements configurable buffering, connections pooling, and automatically groups similar metrics using Khronus message syntax to optimize the amount of bytes transfered to the server.

Installation

$ npm install khronus --save

Example

const Khronus = require("khronus");

var khronus = Khronus({
    "appName": "testApp", //Application name
    "url":"http://myserver:8080/khronus/", //Full Khronus URL to post metrics.
    "maxBufferMeasures":10000, //Maximum number of metrics to buffer before flushing to server.
    "maxBufferTime":1000, //Maximum time in milliseconds to buffer metrics before flushing to the server.
    "maxSockets":10, //Maximum number of sockets to allow per host.
    "maxFreeSockets":5, //Maximum number of sockets to leave open in a free state.
    "requestTimeout":1000 //Time in milliseconds to wait before aborting posts to server
});

//Counters
khronus.incrementCounter("testCounter");
khronus.incrementCounter("testCounter",10); //With custom increment
khronus.incrementCounter("testCounter",10,1473799222712); //With custom increment and timeStamp

//Timers
khronus.recordTime("testTimer",234);
khronus.recordTime("testTimer",567,1473799222712); //With custom timeStamp

//Gauges
khronus.recordGauge("testGauge",234);
khronus.recordGauge("testGauge",567,1473799222712); //With custom timeStamp

//Forcing buffer flush
khronus.flush();

//Rease resources
khronus.shutDown();

Constructor

The constructor returns an instance of a Khronus client when calling it with an options param.

const Khronus = require("khronus");
var client = Khronus(options);

Options

• appName: The name that identifies the current application. This app name will be prepended to all the metrics to guarantee uniqueness in Khronus.
• url: The full Khronus server URL to post the metrics.
• maxBufferMeasures (optional, default: 5000) Maximum number of metrics to buffer before flushing to server.
• maxBufferTime (optional, default: 3000)Maximum time in milliseconds to buffer metrics before flushing to the server.
• maxSockets: (optional, default: 10) Maximum number of sockets to allow per host.
• maxFreeSockets (optional, default: 5) Maximum number of sockets to leave open in a free state.
• requestTimeout (optional, default: 1000) Time in milliseconds to wait before aborting posts to server.
• httpKeepAliveInterval (optional, default: 1000) Time between KeepAlive packets sent to the server.

Client

Client inherits from events.EventEmitter. See custom emitted events below.

Methods

incrementCounter(name , increment)

Used to measure a counter. name is the counter name, increment is an integer with the value to be incremented, it has a default of 1, and timestamp is used when you want to specify one. If not, the current time will be used.

khronus.incrementCounter("testCounter");
khronus.incrementCounter("testCounter",10); //With custom increment
khronus.incrementCounter("testCounter",10,1473799222712); //With custom increment and timeStamp

recordTime(name, time , timestamp)

Used to measure a timer. name is the timer name, time is an integer with the value to be recorded, and timestamp is used when you want to specify one. If not, the current time will be used.

khronus.recordTime("testTimer",234);
khronus.recordTime("testTimer",567,1473799222712); //With custom timeStamp

recordGauge(name, value , timestamp)

Used to measure a gauge. name is the gauge name, value is an integer with the value to be recorded, and timestamp is used when you want to specify one. If not, the current time will be used.

khronus.recordGauge("testGauge",234);
khronus.recordGauge("testGauge",567,1473799222712); //With custom timeStamp

flush()

Used to force a client buffer flush to the server

khronus.flush()

shutDown()

It releases allocated resources (buffer timers, connections, etc). It should be called before shutting down the containing process.

process.on("SIGTERM", () => {
    khronus.shutDown();
});

Events

sendPost

Emitted when the client flushes it's buffer to the client. It receives the byteLength of the message posted.

khronus.on("sendPost", (byteLength) => {
    console.log(byteLength + " bytes sent to the server");
});

sendPostError

Emitted when an error is raised when trying to flush the client's buffer to the server. It receives the error as a param.

khronus.on("sendPostError", (error) => {
    console.log(error);
});

bufferTimedFlush

Emitted when the configured maxBufferTime is reached, and the client is going to flush the it's buffer to the server. It receives the measuresInBuffer as a param.

khronus.on("bufferTimedFlush", (measuresInBuffer) => {
    console.log("Max buffering time was reached: " + measuresInBuffer + " measures are going to be sent to the server");
});

bufferThresholdFlush

Emitted when the configured maxBufferMeasures is reached, and the client is going to flush the it's buffer to the server. It receives the measuresInBuffer as a param.

khronus.on("bufferThresholdFlush", (measuresInBuffer) => {
    console.log("Max buffering measures was reached: " + measuresInBuffer + " measures are going to be sent to the server");
});

bufferFlushStart

Emitted when the client is starting to flush the it's buffer to the server. It receives the measuresInBuffer as a param.

khronus.on("bufferFlushStart", (measuresInBuffer) => {
    console.log("Staring to send " + measuresInBuffer + " measures to the server");
});

bufferFlushError

Emitted when the client finished flushing it's buffer to the server. It receives the measuresInBuffer as a param.

khronus.on("bufferFlushError", (measuresInBuffer) => {
    console.log(measuresInBuffer + " measures where flushed to the server");
});

flushError

Emitted when an error is raised when trying to flush the client's buffer to the server. It receives the error as a param.

khronus.on("flushError", (error) => {
    console.log(error);
});

Develop

Clone the repo:

$ git clone https://github.com/despegar/khronus-nodejs-client.git

Install npm dependencies:

$ cd khronus-nodejs-client
$ npm install

Run tests and generate coverage reports:

$ npm test

The coverage report should be generated on coverage/lcov-report/index.html, and can be opened with a browser.