StatsD Route Monitoring Middleware for Express

0.3.0 verified Thu Apr 23 auth: no javascript abandoned

express-statsd is a middleware for Connect and Express applications designed to send route-specific metrics (status codes and response times) to a StatsD server. The current and only stable version is 0.3.0, which was last published over 12 years ago, indicating the project is abandoned. While functional, developers should be aware that it is not actively maintained and may not be compatible with modern Node.js or Express versions without potential issues. Newer, actively maintained alternatives like `express-hot-shots` (a direct fork) or comprehensive monitoring solutions like `express-insights` and `express-status-monitor` offer more features, better compatibility, and ongoing support. This middleware distinguishes itself by its simplicity, focusing solely on basic route-level HTTP metrics.

Common errors

error TypeError: expressStatsd is not a function ↓

cause Attempting to import `express-statsd` using ES Modules `import` syntax in a pure ESM project, or incorrect `require()` usage.

fix

This package is CommonJS-only. Ensure you are using const expressStatsd = require('express-statsd'); in a CommonJS environment or project configured for CommonJS interop.

error Error: Cannot find module 'express-statsd' ↓

cause The package `express-statsd` has not been installed or is not correctly resolved in your project's `node_modules`.

fix

Run npm install express-statsd or yarn add express-statsd in your project directory to install the package.

Warnings

breaking The `express-statsd` package is abandoned and has not been updated in over 12 years (last published Feb 12, 2014). It may have compatibility issues with modern Node.js versions (e.g., >=16.x) and recent Express.js major versions (e.g., Express 5.x) due to changes in core APIs or internal middleware mechanics. Consider using actively maintained forks like `express-hot-shots` or alternative monitoring solutions. ↓

fix Migrate to a maintained alternative such as `express-hot-shots` or a more comprehensive monitoring library like `express-status-monitor` or `express-insights` for long-term stability and security.

gotcha By default, `express-statsd` sends generic 'status_code' and 'response_time' metrics. To get meaningful, route-specific statistics, it is highly recommended to set `req.statsdKey` within your route handlers or a preceding middleware. This namespaces the metrics, providing better insights into individual endpoints. ↓

fix Implement a middleware or set `req.statsdKey` in your route handler before the response is sent. Example: `req.statsdKey = ['http', req.method.toLowerCase(), 'my_route'].join('.');`

gotcha The default StatsD client `lynx` (and thus `express-statsd`) relies on UDP for sending metrics. UDP is a 'fire-and-forget' protocol, meaning there's no guarantee of delivery. If your StatsD daemon is not running or is configured incorrectly, metrics will be silently dropped without error feedback from `express-statsd` itself. ↓

fix Ensure your StatsD daemon is actively running and listening on the configured host and port (default: 127.0.0.1:8125). Implement external monitoring for your StatsD daemon and consider adding logging for the `lynx` client's error events if you need more visibility into transmission failures.

Install

npm install express-statsd

yarn add express-statsd

pnpm add express-statsd

Imports

expressStatsd
wrong
```
import expressStatsd from 'express-statsd';
```
correct
```
const expressStatsd = require('express-statsd');
```
This package is CommonJS-only. Use `require()` for Node.js environments. ESM imports will fail unless transpiled or using an interop layer.

Quickstart

This example demonstrates how to integrate `express-statsd` globally and, crucially, how to use `req.statsdKey` to namespace metrics per route for more granular monitoring.

const express = require('express');
const expressStatsd = require('express-statsd');
const app = express();

// A helper function to set a custom statsd key per route
function statsd (path) {
  return function (req, res, next) {
    const method = req.method || 'unknown_method';
    req.statsdKey = ['http', method.toLowerCase(), path].join('.');
    next();
  };
}

// Apply the express-statsd middleware globally. 
// Metrics will be generic if req.statsdKey is not set per route.
app.use(expressStatsd({
  client: { host: '127.0.0.1', port: 8125 } // Customize StatsD client options
}));

// Example route with a specific statsd key
app.get('/', statsd('home'), function (req, res) {
  res.send('Hello World!');
});

// Another route with a different statsd key
app.get('/api/users', statsd('api.users.list'), function (req, res) {
  res.json([{ id: 1, name: 'Alice' }]);
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server listening on port ${PORT}`);
  console.log('Ensure a StatsD daemon is running (e.g., `statsd -p 8125`) to receive metrics.');
});