Prometheus Client for Node.js

Common errors

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

  cause Attempting to register a metric with a name that is already in use by another metric within the same registry.
  fix Ensure each metric has a unique name within a given `Registry` instance. If you intend to use a single global metric, define it once and reuse the instance. If using multiple registries, ensure the metric is only registered to its intended registry.

• TypeError: Cannot read properties of undefined (reading 'inc')

  cause Attempting to interact with a metric (e.g., `inc()`, `set()`) before it has been properly initialized or if the variable holding the metric instance is `undefined`.
  fix Verify that the metric object is correctly instantiated and assigned before any operations are performed on it. This often happens if a metric is defined conditionally or in a scope where it's not accessible.

• Error: Labels are not unique.

  cause When defining a metric with `labelNames`, providing duplicate names in the array.
  fix Review the `labelNames` array provided in the metric constructor and remove any duplicate label names. Each label name must be unique.

• Error: Missing label 'method' on metric 'my_app_http_requests_total'

  cause When observing a metric (e.g., `inc()`, `set()`), required labels defined in `labelNames` were omitted or misspelled.
  fix Ensure all labels specified in the `labelNames` array during metric definition are provided when observing the metric, with exact matching keys. For example, if `labelNames: ['method']` then call `inc({ method: 'GET' })`.

Warnings

• breaking Version 15.0.0 dropped support for Node.js versions 10, 12, 14, 17, and 19. Applications on these older Node.js versions must upgrade their Node.js runtime or stay on a `prom-client` version below 15.0.0.
  Fix: Upgrade your Node.js runtime to version 16, 18, or 20 (or higher) to use `prom-client` v15+ features and bug fixes. Alternatively, pin `prom-client` to a 14.x version.
• gotcha When using Node.js's `cluster` module, individual worker metrics will not provide a complete view. Metrics need to be aggregated from all workers in the master process to get accurate global metrics. Custom metrics require configuring the `aggregator` property for correct aggregation.
  Fix: Implement the `AggregatorRegistry` pattern as shown in the `example/cluster.js` to aggregate metrics across workers. For custom metrics, set the `aggregator` property (e.g., 'sum', 'first', 'min', 'max', 'average', 'omit') in the metric config.
• gotcha Some default metrics, specifically those concerning File Descriptors and Memory details, are only available on Linux operating systems. On other platforms (e.g., macOS, Windows), these metrics will not be collected or exposed.
  Fix: Be aware of platform limitations when relying on specific system-level default metrics. Consider custom metrics or external node exporters for cross-platform system metrics if strict parity is required.
• gotcha Incorrectly formatted or non-unique labels can lead to errors during metric creation or observation. Labels must adhere to Prometheus naming conventions, and each unique combination of labels for a given metric should ideally represent a distinct series.
  Fix: Ensure label names are valid Prometheus identifiers (e.g., `[a-zA-Z_:][a-zA-Z0-9_:]*`). Verify that label values are correctly supplied and that you are not accidentally creating an unbounded number of label combinations (high cardinality).
• breaking Version 15.0.0 introduced support for OpenMetrics and Exemplars. While this adds powerful new capabilities, consuming Prometheus servers or scrapers must be compatible with OpenMetrics format if these features are used. The `contentType` constant was also adjusted for these formats in v15.1.2.
  Fix: Ensure your Prometheus server or scraping agent is configured to accept OpenMetrics format if you are leveraging Exemplars or the new format features. Use `Registry.PROMETHEUS_CONTENT_TYPE` or `Registry.OPENMETRICS_CONTENT_TYPE` for setting the `Content-Type` header appropriately.

Install

• npm install prom-client npm
• yarn add prom-client yarn
• pnpm add prom-client pnpm

Imports

• Registry
  wrong:

  const Registry = require('prom-client').Registry;

  correct:

  import { Registry } from 'prom-client';

  The common practice is to import named exports. While CJS require works, ES module imports are preferred in modern Node.js development.
• collectDefaultMetrics
  wrong:

  import collectDefaultMetrics from 'prom-client';

  correct:

  import { collectDefaultMetrics } from 'prom-client';

  `collectDefaultMetrics` is a named export, not the default export.
• Counter
  wrong:

  const Counter = require('prom-client').Counter;

  correct:

  import { Counter } from 'prom-client';

  Metric types (Counter, Gauge, Histogram, Summary) are named exports and should be imported directly.

Quickstart

This quickstart demonstrates how to set up an Express.js server, collect default Node.js metrics, define a custom counter, and expose them on a /metrics endpoint, all using a dedicated Prometheus registry.

import express from 'express';
import { collectDefaultMetrics, Registry, Counter } from 'prom-client';

const app = express();
const port = process.env.PORT || 3000;

// Create a new registry to register custom metrics
const register = new Registry();

// Collect default metrics like CPU, memory, event loop lag, etc.
// These are registered to the custom 'register' instance.
collectDefaultMetrics({
  register: register,
  prefix: 'my_app_',
  labels: { APP_NAME: 'my_service' }
});

// Create a custom counter metric
const httpRequestCounter = new Counter({
  name: 'my_app_http_requests_total',
  help: 'Total number of HTTP requests',
  labelNames: ['method', 'route', 'status'],
  registers: [register]
});

// Example route to increment the counter
app.get('/', (req, res) => {
  httpRequestCounter.inc({ method: 'GET', route: '/', status: 200 });
  res.send('Hello World!');
});

// Expose metrics at the /metrics endpoint
app.get('/metrics', async (req, res) => {
  res.set('Content-Type', register.contentType);
  res.end(await register.metrics());
});

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