express-hot-shots

StatsD route monitoring middleware for Connect/Express. This middleware can be used either globally or on a per-route basis (preferred) and sends status codes and response times to StatsD.

Forked from uber/express-statsd for usage in Spectrum.

Installation

1npm install express-hot-shots

Usage

An example of an express server with express-hot-shots:

1var express = require('express');
2var statsd = require('express-hot-shots');
3var app = express();
4
5app.use(statsd());
6
7app.get('/', function (req, res) {
8  res.send('Hello World!');
9});
10
11app.listen(3000);

By default, the middleware will send status_code and response_time stats for all requests. For example, using the created server above and a request to http://localhost:3000/, the following stats will be sent:

status_code.200:1|c
response_time:100|ms

Per route example

However, it's highly recommended that you set req.statsdKey which will be used to namespace the stats. Be aware that stats will only be logged once a response has been sent; this means that req.statsdKey can be set even after the express-hot-shots middleware was added to the chain. Here's an example of a server set up with a more specific key:

1var express = require('express');
2var expressStatsd = require('express-hot-shots');
3var app = express();
4
5function statsd (path) {
6  return function (req, res, next) {
7    var method = req.method || 'unknown_method';
8    req.statsdKey = ['http', method.toLowerCase(), path].join('.');
9    next();
10  };
11}
12
13app.use(expressStatsd());
14
15app.get('/', statsd('home'), function (req, res) {
16  res.send('Hello World!');
17});
18
19app.listen(3000);

A GET request to / on this server would produce the following stats:

http.get.home.status_code.200:1|c
http.get.home.response_time:100|ms

Tags

You can set the tags of the metrics with the req.statsdTags property.

1
2function statsd (path) {
3  return function (req, res, next) {
4    var method = req.method || 'unknown_method';
5    req.statsdKey = ['http', method.toLowerCase(), path].join('.');
6    req.statsdTags = {
7      server: process.env.SERVER_NAME,
8    }
9    next();
10  };
11}

These will be sent with both the response time and status code metrics.

Plain http example

This module also works with any http server

1var http = require('http');
2var expressStatsd = require('express-hot-shots');
3
4var monitorRequest = expressStatsd();
5
6http.createServer(function (req, res) {
7    monitorRequest(req, res);
8
9    // do whatever you want, framework, library, router
10    res.end('hello world');
11}).listen(3000);

Options

1expressStatsd(options);

• options Object - Container for settings
  • client HotShots instance - a custom hot shots instance
  • hotShots Object - The hotShots options if you don't want to provide your own instance
  • requestKey String - The key on the req object at which to grab the key for the statsd logs. Defaults to req.statsdKey.