Registry / observability / prometheus-middleware

prometheus-middleware

library1.4.2jsnpmunverified

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.

observability http-networking web-framework devops

npm install prometheus-middleware

github ↗package ↗

INSTALL

IMPORT

SIG · PROMETHEUS-MIDDLEW

prometheus-middleware

observabilityjavascriptv1.4.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

APM

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

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

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.

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); }); });

Debug

Known issues

gotchaBy 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.

affects: >=1.0.0

breakingThe 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.

affects: <1.0.0

gotchaWhile 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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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');`.

TypeError: APM is not a constructor

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';`.

metrics_path_label_cardinality_high

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.

Upgrade

Version history

1.4.2latest on npm

Audit

Dependencies

prom-clientrequiredCore metrics collection library used internally and exposed for custom metric definitions.

Agent activity

17 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/VoodooTeam/prometheus-middleware ↗

packagehttps://www.npmjs.com/package/prometheus-middleware ↗