Librato Express

Librato metrics client.

This module provides methods to perform common operations for aggregating and sending metrics results to Librato backend. It exposed expressjs middleware as well as gives direct access to underliyng metrics keeping classes.

Middleware example

var metrics = require('librato-express');
var app = require( 'express' )();

// initialize with your librato credentials
metrics.initialise({
    email : '[email protected]',
    token : 'libratoGeneratedToken'
});

metrics.start();

// call metrics functions on desired routes
app.use('/', metrics.middleware.routeCount({name: 'route_visited'}));
app.use('/user', metrics.middleware.routeTiming({name: 'user_load_response_time'}));

Stand-alone example

var metrics = require('librato-express');
var counter = new metrics.Counter({name: 'some_function_call'});

metrics.initialise({
    email : '[email protected]',
    token : 'libratoGeneratedToken'
});
metrics.start();

function doSomething () {
	counter.increment();
	...
}

Documentation

Main

• Metrics.initialise
• Metrics.flush
• Metrics.start
• Metrics.deleteAllMetrics

Middleware

• Metrics.middleware.routeCount
• Metrics.middleware.routeTiming

Metrics Classes

• Metrics.Counter
• Metrics.Timing

Annotations

• Metrics.Annotation

Worker Classes

• Collector
• Transport

Main

Metrics.initialise(options)

Set-up librato-express module using this function. It should be called before anything else.

• options.email - Librato account email.
• options.token - Librato provided token.
• options.period - Minimum frequency of sending librato metrics. Defaults to 1 second.
• options.prefix - Prefix to be used with all metric names. Defaults to empty string.
• options.source - Global metrics source property. Default: os.hostname() value.

It is possible to replace default behaviour of librato-express by providing replacement implementation for the following two components.

• options.collector - Caching object responsible for temporary storing metrics before sending those to Librato.
• options.transport - Https client.

Metrics.flush(callback)

Dumps accumulated data to Librato.

• callback() - callback function.

Metrics.start()

Starts calling metrics.flush() function in a forever circle.

Metrics.deleteAllMetrics( [callback] )

Deletes all metrics from Librato that start with Base.options.prefix. Note: If prefix was not specified this method will delete all metrics from the account.

• [callback()] - optional callback function.

Middleware

Metrics.middleware.routeCount(options[, filter])

Creates middleware function that when invoked by express router will increment a metric with a specified name.

• options.name - Name of the metric for Librato. Note: options.prefix will be applied to this value.
• options.period - Period of sending this metric to Librato. Defaults to Librato default period of 60 seconds.
• options.source - Librato source name for this metric.
• options.ignoreNonDirty - If set will prevent sending to Librato if this metric did not increment. Defaults to true.
• options.alert - Object describing custom alert definition. Note that this is not a Librato Alert.
  • alert.trigger(metric) - Function accepting metric object which is about to be sent to Librato. Must return a boolean value to trigger an alert hook.
  • alert.handler(metric) - This function will be called if trigger returned true.
• filter - This is a postfix to apply to metric name. Can be either a string or a function.
  • String - matches property in the request object for the route. It can be delimited with any non-word character to match property in the nested object. Note that no type checks are performed and is solely up to a client to make sure references are present.
  • Function - will receive request object for the route and should return a string value representing a filter key. Returned value ofnull will cause the filter to be ignored.

// Make sure request object has 'userID' property.
app.param('userID', function (req, res, next, value) {
	req.userID = value;
});

// Will increment metric key of "count_visit_someUserID".
app.use('/', metrics.middleware.routeCount({name: 'visit'}), 'userID');

// Will increment metric key of "count_check_MY_FILTER".
app.use('/', .middleware.routeCount({name: 'check'}, function ( request ) {
	return 'MY_FILTER';
}));

Metrics.middleware.routeTiming(options[, filter])

Same as routeCount but will aggregate the delay values into a gauge specific parameters set.

Time will be sampled from the position of this function in the stack and untill express.response.send function is finished.

• count
• min
• max
• sum_squares

Metrics Classes

These two objects can be used outside middleware to perform same tasks (in fact that is what middleware functions use under the hood).

Metrics.Counter(options)

Creates a new Counter object. Options are the same as in routeCount

increment([filter])

Increment counter value.

• filter - Optional string value to append to metric name key.

deleteMetrics()

Deletes all metrics from Librato that start with the name of this metric class instance.

Metrics.Timing(options)

Creates a new Timing object. Options are the same as in routeCount

measure(time[, filter])

Increment counter value.

• time - Time in the past to take the measurement from.
• filter - Same as in Counter.increment.

deleteMetrics()

Same as Counter.deleteMetrics.

Annotations

Metrics.Annotation(stream, options)

Creates new annotation object assigned to a specific stream.

• stream - Name of the stream.
• options.title - Title of this annotation. Defaults to name of the stream.
• options.source - An optional name of the source for this annotation.
• options.description - An optional description.
• options.links - Optional list of links for this annotation.

var metrics = require('librato-express');
...

var ann = new metrics.Annotation('some-annotation-stream', {
	title : 'my-annotation',
	links : [{rel: 'librato', href: 'http://dev.librato.com/v1/annotations'}]
});
ann.post();

setTimeout(function () {
	ann.post(); // Lets POST re-occurring instance of this event
}, 300000);

var other = new metrics.Annotation('some-annotation-stream', {title : 'my-other-annotation'});
other.startMs(Date.now()-300000); // It actually occurred 5 minutes ago ;)
other.endMs(); // And lasted until now
other.post();

startMs([time])

Sets start time for the next occurrence of annotation. Returns unix timestamp which will be sent to Librato.

• time - Optional time in milliseconds. This will be converted into unix timestamp.

endMs([time])

Same as startMs.

post([callback])

Posts annotation to Librato. Start and end timestamps are cleared immediately after this operation.

Worker Classes

These workers encapsulate 'behind the scenes' algorithms for the main functionality of the module. It is possible to implement custom strategies and replace default behaviour while initialising librato-express.

Collector()

Provides routines to temporary store and process metrics before sending to Librato.

count(key, filter, callback)

Increment count values.

• key - name of Librato metric.
• filter - filter to apply to name.
• callback() - callback function.

timing(key, duration, filter, callback)

Add to duration values.

• key - name of Librato metric.
• duration - next duration to log.
• filter - filter to apply to name.
• callback() - callback function.

flush(callback)

Dump accumulated data.

• callback({}) - Call this when finished with the metrics data object. Note: librato-express will ignore if null and undefined values.

Transport(options)

Simple HTTPS client to send data over network.

• options.email - Librato account email.
• options.token - Librato provided token.
• options.silent - Flag to never pass connection information to callee.

postMetrics(metric[, callback])

Send metric data to librato.

• metric - Actual data to send.
• callback([err]) - optional callback function.

deleteMetrics(names[, callback])

Delete metrics from librato.

• names - list of name strings to send.
• callback([err]) - optional callback function.

postAnnotation(stream, data[, callback])

Posts annotation.

• stream - name of the stream to POST into.
• data - annotation body.
• callback([err]) - optional callback function