Prometheus client_js: Node.js Metrics Client

Understanding the Prometheus Node.js Client

Prometheus client for Node.js is prometheus/client_js, a JavaScript library in the Prometheus GitHub org that implements four metric types — Counter, Gauge, Histogram, and Summary — plus a registry that formats them into scrape-ready text. It doesn't run an HTTP server itself; you decide how `/metrics` gets served. It also understands Node.js's `cluster` module and can emit OpenMetrics.

Core Features for Node.js Application Monitoring

• ✓Four Prometheus metric types — Counter (`inc()`), Gauge (`set()`/`inc()`/`dec()`/`setToCurrentTime()`), Histogram (`observe()` with configurable buckets), and Summary (`observe()` with configurable percentiles and an optional sliding time window via `maxAgeSeconds`/`ageBuckets`).
• ✓`collectDefaultMetrics()` pulls in the metrics Prometheus itself recommends plus Node.js-specific ones — event loop lag, active handles, garbage collection, Node.js version — with config knobs like `prefix`, `gcDurationBuckets`, and `eventLoopMonitoringPrecision`.
• ✓Cluster-mode aggregation through `ClusterRegistry` and `AggregatorRegistry`, so `register.clusterMetrics()` merges every worker's numbers instead of a scrape only ever reaching one process.
• ✓Label support with three equivalent syntaxes for setting labeled values, label-aware timers, and a `zero()` method to pre-register histogram label combinations before they've been observed.
• ✓Per-registry default labels via `register.setDefaultLabels()`, applied automatically to every metric that registry emits.
• ✓Switchable exposition format — classic Prometheus text (0.0.4) or OpenMetrics (1.0.0) — set per registry with `register.setContentType()`.
• ✓Exemplars on Counter and Histogram metrics, with default metrics auto-populating `traceId`/`spanId` exemplar labels when OpenTelemetry is present.
• ✓A `Pushgateway` client (`pushAdd`, `push`, `delete`) for jobs that can't sit around waiting to be scraped, plus `linearBuckets()`/`exponentialBuckets()` helpers for histogram configuration.

Getting Started with Prometheus client_js

The README doesn't spell out an npm install command in its Usage or API sections — every code sample imports the library the same way, `require('@prometheus-io/client')`, which tells you the package identifier but not the exact install invocation. What it does point to for a working setup is the `example/` folder, referenced specifically for cluster and server usage rather than described inline.

Instrumenting Your Node.js Application with Metrics

The basic loop is: create a metric with a mandatory `name` and `help`, call `.inc()`/`.set()`/`.observe()` on it as your code runs, then answer Prometheus's scrape request with `await registry.metrics()` from whatever HTTP handler you're already running — the library doesn't bundle a web framework, so that route is yours to wire up. For values you can only read at scrape time, like current memory usage rather than something accumulated continuously, pass a `collect()` function instead of updating the metric on a timer; the README is specific that `collect()` — sync or async — fires when the registry gathers values, and a `setInterval` callback is the wrong place for those writes. Labels come from a `labelNames` array on the metric config, then get filled in through `.labels(...).set(...)` or by passing a labels object as the first argument to a call like `.inc()`. Running under Node.js's `cluster` module changes the picture: a worker's local registry only reflects that worker's own numbers, so you instantiate `ClusterRegistry` before branching on `cluster.isPrimary`. Skipping that setup in a worker leaves it unable to answer when the primary asks it to aggregate, so `clusterMetrics()` just stalls until it times out. Custom metrics sum across workers by default; set `aggregator` in the metric config to `'first'`, `'min'`, `'max'`, `'average'`, or `'omit'` when summing isn't the right combination for that particular metric.

Alternatives for Node.js Metrics Collection

Frequently Asked Questions

The problem it solves

A Node.js process that's slow or failing under load won't tell you why unless something inside it is counting requests, timing them, and tracking memory and event-loop health in a format your monitoring stack can actually scrape. Hand-rolling that layer — picking histogram bucket boundaries, formatting Prometheus's exposition text by hand, keeping Counters from ever going backward — is easy to get subtly wrong. prometheus/client_js exists to standardize that instrumentation layer instead of every team inventing its own metric-naming and formatting conventions.

Best use cases

• •Instrumenting a Node.js HTTP API with request-count Counters and request-duration Histograms that a Prometheus server scrapes on an interval.
• •Aggregating metrics across a Node.js `cluster` deployment where each worker would otherwise only expose its own local numbers.
• •Correlating metrics with distributed traces by attaching exemplars to Counters and Histograms once OpenTelemetry is populating trace and span IDs.
• •Pushing metrics from short-lived batch or cron jobs to a Pushgateway instead of standing up a long-lived process for Prometheus to scrape.
• •Moving a registry from the classic Prometheus text format to OpenMetrics without rewriting the metric-type code that produces the values.

Who should try it — and who should skip

Try Prometheus client for Node.js if you're already running Prometheus, or anything OpenMetrics-compatible, and want real Counter/Gauge/Histogram/Summary types with working cluster-mode aggregation instead of formatting exposition text by hand. Skip it if you don't want to own the `/metrics` HTTP route and a scrape target yourself — an all-in-one APM agent that ships its own collector and dashboard gets you visibility with less setup, at the cost of tying your data to that vendor.

Related repositories