khronus
v1.0.0
Published
Client for Khronus time series DB
Downloads
11
Maintainers
Readme
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] [, timestamp])
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.