Registry / observability / http-metrics-middleware

http-metrics-middleware

JSON →
library2.2.1jsnpmunverified

http-metrics-middleware is an Express.js middleware designed to integrate Prometheus metrics into Node.js applications, currently stable at version 2.2.1. It provides a convenient wrapper around `prom-client`, offering a set of default HTTP request metrics such as duration histograms and summaries, as well as status code counts. The library maintains a regular release cadence, primarily driven by dependency updates, security patches, and minor enhancements. Key differentiators include its configurable options for metric labels, such as normalized URL paths, and custom time/quantile buckets, allowing fine-grained control over the collected data. While primarily built for Express, it can be seamlessly integrated into Koa applications using `koa-connect`. It focuses on providing a robust, opinionated solution for common HTTP metrics without requiring extensive manual setup of individual `prom-client` metrics.

npm install http-metrics-middleware
INSTALL
IMPORT
SIG · HTTP-METRICS-MIDDL
H
http-metrics-middleware
observabilityjavascriptv2.2.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MetricsMiddleware
const MetricsMiddleware = require('http-metrics-middleware')
import { MetricsMiddleware } from '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
app.use(metrics.initRoutes())
app.use(metrics.initRoutes)
`initRoutes` is a function that returns the actual middleware. It must be called to be used correctly with `app.use`.

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`); });
Debug
Known issues
breakingVersion 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.
affects: >=1.2.0
gotchaEnabling 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.
affects: >=1.0.0
breakingUpdates 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.
affects: >=2.1.2
breakingIn 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`.
affects: >=2.1.5
Errors
Common errors & fixes
ReferenceError: MetricsMiddleware is not defined
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
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.
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.
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.
Upgrade
Version history
2.2.1latest on npm
Audit
Dependencies
expressoptionalPrimary framework for which the middleware is designed.
prom-clientrequiredCore Prometheus client library that this middleware wraps and exposes.
koa-connectoptionalRequired for integrating the middleware with Koa applications.
Agent activity
11 hits · last 30 days
node
10
OpenAI (training)
1
Resources
http-metrics-middleware — npm install http-metrics-middleware · libregistry