prom-client

prom-client is a Node.js library for exposing application metrics in the Prometheus exposition format. It implements the four core Prometheus metric types — Counter, Gauge, Histogram, and Summary — along with a Registry that collects and serializes them into the text format Prometheus scrapes over HTTP. It does not bundle a web framework of its own; instead, applications wire register.metrics() into whatever HTTP server or framework they already use to expose a /metrics endpoint.

Beyond custom metrics, the library ships collectDefaultMetrics() for automatic collection of Node.js and process-level signals recommended by Prometheus itself — event loop lag, active handles, garbage collection duration, heap and memory usage, process CPU time, open file descriptors, and Node.js version. For multi-process deployments it provides cluster and worker-thread aggregation registries that merge metrics across workers with configurable aggregation strategies (sum, min, max, average, first, or omit), plus a Pushgateway client for batch/cron-style jobs that can’t be scraped directly.

The project began life as prom-client and has since been adopted as the official Node.js client under the Prometheus GitHub organization (now published as @prometheus-io/client, with prom-client preserved as the long-standing, widely-depended-upon package name most of the ecosystem still installs). It supports both the legacy Prometheus text exposition format and the newer OpenMetrics format, including OpenMetrics exemplars tied to OpenTelemetry trace and span IDs.

What You Get

• Counter, Gauge, Histogram, and Summary metric types with full label support, including strongly-typed labels via TypeScript’s as const
• collectDefaultMetrics() for automatic Node.js/process metrics: event loop lag and utilization, GC duration, heap and memory stats, CPU time, file descriptors, and version info
• Multi-registry support so different parts of an application (or different metric sets) can be scraped independently, plus a Registry.merge() to combine them on one endpoint
• Cluster and worker-thread aggregation registries with per-metric aggregator strategies (sum, min, max, average, first, omit) for accurate metrics across multiple Node.js processes
• Pushgateway client for pushing metrics from short-lived or batch jobs that Prometheus can’t scrape directly
• Dual exposition format support — classic Prometheus text format and OpenMetrics, including OpenMetrics exemplars linked to OpenTelemetry trace/span IDs

Common Use Cases

• Exposing a /metrics endpoint from an Express, Fastify, or plain http.Server-based Node.js API for Prometheus to scrape
• Tracking HTTP request duration and count with labeled Histograms to power latency/error-rate dashboards and SLO alerts
• Monitoring Node.js runtime health (event loop lag, GC pauses, memory growth) to catch performance regressions before they page someone
• Aggregating metrics across a Node.js cluster or worker-thread pool so a single scrape reflects the whole process group, not just one worker
• Pushing job-completion metrics from cron jobs or one-off scripts via the Pushgateway client, since those processes exit before Prometheus can scrape them

Under The Hood

Architecture The library centers on a Registry (lib/registry.js) that metrics register themselves into at construction time, and an abstract Metric base class (lib/metric.js) that Counter, Gauge, Histogram, and Summary each extend — validating names and label names up front and throwing on misconfiguration rather than failing silently later. ClusterRegistry and WorkerRegistry (lib/cluster.js, lib/worker.js) extend this model across process boundaries, using IPC to collect and merge metric snapshots from workers according to a per-metric aggregator strategy defined in lib/metricAggregators.js. Pushgateway (lib/pushgateway.js) is a separate, self-contained concern layered on top of the same Registry abstraction rather than woven into it, and shared low-level exposition-format and escaping logic lives in lib/util.js. The design favors flat, single-responsibility modules over deep class hierarchies or a plugin system, which keeps the failure surface small and each file’s job easy to state in one sentence.

Tech Stack The implementation is plain JavaScript with hand-written TypeScript declarations (index.d.ts, ~900 lines) rather than a compiled TypeScript source — tsc is used only to type-check the codebase, not to build it. Runtime dependencies are deliberately minimal: @opentelemetry/api (only exercised when OpenMetrics exemplars are enabled) and tdigest (for the sliding-window quantile estimation behind Summary metrics). Tooling is modern and actively maintained: ESLint 10 with typescript-eslint, eslint-plugin-n, and eslint-plugin-jsdoc, Prettier for formatting, Husky plus lint-staged for pre-commit enforcement, and GitHub Actions workflows for CI, changelog generation, and release automation. The package targets current Node.js LTS lines only, reflecting its role as low-level, performance-sensitive infrastructure rather than a broadly polyfilled utility library.

Code Quality Every core module in lib/ has a corresponding test file under test/ (counterTest.js, gaugeTest.js, histogramTest.js, summaryTest.js, registerTest.js, clusterTest.js, workerTest.js, pushgatewayTest.js, validationTest.js, utilTest.js, aggregatorsTest.js, timeWindowQuantilesTest.js, plus a dedicated typescript.ts file that exercises the type definitions themselves), run via Jest with coverage collection wired into the test script. Constructors validate their inputs eagerly — missing help text, missing names, invalid metric or label names, and invalid content types all throw immediately rather than producing malformed output downstream. Naming is consistent and domain-accurate throughout (Registry, Metric, Grouper, aggregators), and the codebase is fully linted and Prettier-formatted with pre-commit enforcement, giving high confidence in consistency across contributors.

What Makes It Unique Most metrics client libraries stop at exposing counters and gauges from a single process. prom-client’s cluster/worker aggregation layer — where each metric declares its own aggregation strategy (sum, min, max, average, first, or omit) and a primary process merges snapshots from all workers over IPC — solves a problem that’s genuinely awkward to get right in Node.js’s multi-process model, and is unusual to see handled this thoroughly in a client library rather than left to the operator. Layered on top of that is dual-format support for both the legacy Prometheus text format and the OpenMetrics standard, including exemplars that attach OpenTelemetry trace and span IDs directly to counter and histogram observations — connecting metrics to distributed traces at the data-model level rather than through a separate correlation step.