Prometheus client for Node.js (`prom-client`) is a comprehensive toolkit for instrumenting Node.js applications with Prometheus metrics. It supports all standard Prometheus metric types including counters, gauges, histograms, and summaries, alongside OpenMetrics and Exemplars which were introduced in version 15.0.0. The package is currently stable at version 15.1.3, with a release cadence that sees frequent patch and minor updates addressing bugs and adding features, while major versions are released less often to accommodate significant changes like Node.js version support adjustments and new Prometheus protocol features. Key differentiators include its robust support for Node.js `cluster` module aggregation, providing sensible defaults for common metrics, and a rich set of built-in 'default metrics' for runtime performance and resource usage. It ships with TypeScript types, enabling strong typing for metric definitions and interactions.
npm install prom-clientVerified import paths — ran on the pinned version, not inferred.
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.
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.
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.
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.
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).
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.
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.
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.
Review the `labelNames` array provided in the metric constructor and remove any duplicate label names. Each label name must be unique.
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' })`.No dependency data recorded yet.