Prometheus Middleware for Node.js HTTP Servers

1.4.2 verified Thu Apr 23 auth: no javascript

The `prometheus-middleware` package provides a straightforward solution for integrating Prometheus metrics into Node.js HTTP applications. Currently at version 1.4.2, it appears to maintain an active development cadence given its continuous integration setup and recent releases. It acts as an abstraction layer, setting up an HTTP server to expose metrics, instantiating and exposing a `prom-client` instance, and patching the native Node.js HTTP server to automatically track request-response times. A key differentiator is its out-of-the-box support for popular Node.js HTTP frameworks like Express and Fastify, along with the default Node.js HTTP server. It also includes sensible defaults, such as normalizing 404 error paths to prevent high cardinality issues in Prometheus, and automatically collects metrics for event loop, garbage collection, CPU, and memory usage. Developers can also easily define custom metrics using the underlying `prom-client` instance.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module ...prometheus-middleware.js not supported. ↓

cause Attempting to use `require()` syntax in an ES Module context, or trying to `import` in a CommonJS context without proper configuration.

fix

If your project is an ESM module (e.g., "type": "module" in package.json), use import APM from 'prometheus-middleware';. If it's CommonJS, use const APM = require('prometheus-middleware');.

error TypeError: APM is not a constructor ↓

cause Incorrectly importing the `APM` class, such as using named import syntax for a default export in CommonJS, or incorrect path.

fix

For CommonJS, use const APM = require('prometheus-middleware');. For ESM, use import APM from 'prometheus-middleware'; or import { APM } from 'prometheus-middleware';.

error metrics_path_label_cardinality_high ↓

cause Prometheus alert indicating too many unique values for the `path` label on HTTP metrics, often due to dynamic URL segments not being normalized.

fix

Review your prometheus-middleware configuration. The default behavior normalizes 404 paths. If this is not sufficient, consider implementing custom path normalization using a library like express-url-trimmer before prometheus-middleware in your HTTP server's middleware chain, or ensure NORMALIZE_ENDPOINT is not set to false without careful consideration.

Warnings

gotcha By default, the middleware normalizes the 'path' label for HTTP 404 responses to avoid high cardinality issues in Prometheus. If your monitoring strategy requires unique path labels for all 404s, you must explicitly set `NORMALIZE_ENDPOINT: false` in the configuration. ↓

fix If unique 404 path labels are required, initialize APM with `new APM({ NORMALIZE_ENDPOINT: false })`. Be aware of potential high cardinality with this setting.

breaking The package requires Node.js version 16.0.0 or higher. Running on older Node.js versions will result in startup failures. ↓

fix Ensure your Node.js environment is updated to version 16.0.0 or later. The package officially tests and supports Node.js 18.x, 20.x, and 22.x.

gotcha While the documentation states `16.x` is supported, the compatibility table explicitly marks it as 'not tested'. Prioritize Node.js 18.x, 20.x, or 22.x for environments where thorough testing has been performed by the library authors. ↓

fix For production deployments, use Node.js versions 18.x, 20.x, or 22.x to benefit from tested compatibility. If using 16.x, ensure thorough application-level testing.

Install

npm install prometheus-middleware

yarn add prometheus-middleware

pnpm add prometheus-middleware

Imports

APM

wrong

import { APM } from 'prometheus-middleware'.APM;

correct

import APM from 'prometheus-middleware';
// Or for the class itself:
import { APM } from 'prometheus-middleware';

The default export is the APM class constructor. Named export also available for clarity.

APM (CommonJS)
```
const APM = require('prometheus-middleware');
```
This is the primary way shown in the documentation examples for Node.js environments.

APM.client.Counter

import APM from 'prometheus-middleware';
const apm = new APM();
const counter = new apm.client.Counter({
  name: 'my_counter',
  help: 'A custom counter metric'
});

Access `prom-client` metric constructors via the `apm.client` instance after initialization.

Quickstart

This quickstart initializes `prometheus-middleware` to expose metrics on port 9350 at `/metrics`. It also demonstrates adding a custom Prometheus counter using `apm.client.Counter` and integrates it into a basic Node.js HTTP server. A graceful shutdown mechanism is included.

import APM from 'prometheus-middleware';
import http from 'http';

const apm = new APM({
  PORT: 9350,
  METRICS_ROUTE: '/metrics'
});
apm.init();

// Example of adding a custom metric
const customRequestsCounter = new apm.client.Counter({
  name: 'custom_http_requests_total',
  help: 'Total number of custom HTTP requests',
  labelNames: ['method', 'route', 'code']
});

// Create a simple HTTP server to demonstrate the middleware
const server = http.createServer((req, res) => {
  if (req.url === '/test') {
    customRequestsCounter.inc({ method: req.method, route: '/test', code: 200 });
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('Hello from /test\n');
  } else {
    res.writeHead(404, { 'Content-Type': 'text/plain' });
    res.end('Not Found\n');
  }
});

server.listen(3000, () => {
  console.log('HTTP server listening on port 3000');
  console.log('Prometheus metrics available at http://localhost:9350/metrics');
});

// Graceful shutdown to destroy the APM instance and its HTTP server
process.on('SIGTERM', () => {
  console.log('SIGTERM received, destroying APM...');
  apm.destroy();
  server.close(() => {
    console.log('HTTP server closed.');
    process.exit(0);
  });
});