HTTP Metrics Middleware

Common errors

• ReferenceError: MetricsMiddleware is not defined

  cause Attempting to import the `MetricsMiddleware` class using ESM `import` syntax (`import { MetricsMiddleware } from 'http-metrics-middleware'`) in a CommonJS module.
  fix Use the CommonJS `require` syntax: `const MetricsMiddleware = require('http-metrics-middleware')`.

• GET /metrics 404 Not Found

  cause The middleware responsible for exposing the Prometheus metrics endpoint was not properly initialized or added to the Express application.
  fix Ensure you have called `app.use(metrics.initRoutes())` after creating an instance of `MetricsMiddleware`.

• Error: A metric with the name http_request_duration_seconds has already been registered.

  cause Attempting to create a custom `prom-client` metric with a name that conflicts with one of the default metrics provided by `http-metrics-middleware`.
  fix Either disable the conflicting default metric via `http-metrics-middleware` options (e.g., `enableDurationHistogram: false`) or choose a unique name for your custom metric.

• Prometheus scrape endpoint returns an empty response or only default Node.js metrics.

  cause The middleware is active but no HTTP requests are being made to your Express application, or the middleware is placed too late in the Express middleware chain to capture requests.
  fix Ensure requests are hitting your application. Place `app.use(metrics.initRoutes())` early in your middleware chain, preferably before any routes that you want to measure. Custom metrics will only appear if their `inc()` or `observe()` methods are called.

Warnings

• breaking Version 1.2.0 and subsequent versions of `http-metrics-middleware` require Node.js v10 or above. Older Node.js environments will not be supported.
  Fix: Upgrade your Node.js runtime environment to version 10 or higher to ensure compatibility.
• gotcha Enabling the `includePath` option can lead to high cardinality in your Prometheus metrics if your application has dynamic URL paths with many unique values. This can drastically increase memory usage and storage requirements for Prometheus.
  Fix: Set `includePath: false` in the middleware options or ensure your `normalizePath` function or Express route definitions heavily restrict path parameters to a limited set of known values.
• breaking Updates to underlying dependencies like `express` (v4.21.2 in v2.2.0, v4.19.2 in v2.1.4) and `prom-client` (v13.1.0 in v2.1.2, latest in v2.1.5) may introduce breaking changes from those libraries. Review their respective changelogs.
  Fix: Carefully review the changelogs of `express` and `prom-client` when upgrading `http-metrics-middleware` to newer versions to anticipate any breaking changes in their APIs or behaviors.
• breaking In version 2.1.5, the archived dev-dependency `@after-work.js/aw` was removed and replaced by `mocha` as part of a CVE fix. While primarily a dev dependency, be aware of changes in the test runner if you integrate with internal testing utilities.
  Fix: No direct user action is typically required for production code, but be aware if your CI/CD or local development environment relied on `@after-work.js/aw`.

Install

• npm install http-metrics-middleware npm
• yarn add http-metrics-middleware yarn
• pnpm add http-metrics-middleware pnpm

Imports

• MetricsMiddleware
  wrong:

  import { MetricsMiddleware } from 'http-metrics-middleware'

  correct:

  const MetricsMiddleware = require('http-metrics-middleware')

  The library primarily uses CommonJS `require()` syntax as shown in official examples. Direct ESM `import` is not officially supported or documented for the main class.
• promClient

  const promClient = require('http-metrics-middleware').promClient

  The underlying `prom-client` instance is exposed as a property on the main module for defining custom metrics.
• initRoutes
  wrong:

  app.use(metrics.initRoutes)

  correct:

  app.use(metrics.initRoutes())

  `initRoutes` is a function that returns the actual middleware. It must be called to be used correctly with `app.use`.

Quickstart

This example demonstrates how to set up `http-metrics-middleware` with Express, configure a custom metrics path, and integrate a custom Prometheus counter using the exposed `promClient` instance.

const express = require('express');
const MetricsMiddleware = require('http-metrics-middleware');
const promClient = require('http-metrics-middleware').promClient;

const app = express();
const port = 3000;

// Initialize the middleware with custom options
const metrics = new MetricsMiddleware({
  metricsPath: '/app-metrics', // Custom path for metrics endpoint
  includePath: true, // Include path label (use with caution for high cardinality)
  timeBuckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1, 2], // More granular buckets
});

// Use the middleware to expose the metrics endpoint
app.use(metrics.initRoutes());

// Example custom metric using the exposed promClient
const myCustomCounter = new promClient.Counter({
  name: 'my_app_custom_operations_total',
  help: 'Total number of custom operations',
  labelNames: ['operation_type'],
});

// Sample API route to increment custom metric
app.get('/api/data', (req, res) => {
  myCustomCounter.inc({ operation_type: 'read' });
  res.status(200).json({ message: 'Data fetched successfully' });
});

app.post('/api/data', (req, res) => {
    myCustomCounter.inc({ operation_type: 'write' });
    res.status(201).json({ message: 'Data created successfully' });
});

// Root route
app.get('/', (req, res) => {
  res.send('Hello from http-metrics-middleware example!');
});

app.listen(port, () => {
  console.log(`Server listening at http://localhost:${port}`);
  console.log(`Prometheus metrics available at http://localhost:${port}/app-metrics`);
});