prom-client

What is prom-client?

The prom-client npm package is a client for the Prometheus monitoring tool, which allows you to collect and expose metrics from your Node.js applications. It supports various metric types, custom labels, and can be integrated with the default Node.js metrics and other systems.

What are prom-client's main functionalities?

Counter

Counters are a metric that only goes up (e.g., page views, total number of requests).

const { Counter } = require('prom-client');
const httpRequestsTotal = new Counter({
  name: 'http_requests_total',
  help: 'Total number of HTTP requests'
});

httpRequestsTotal.inc(); // Increment by 1
httpRequestsTotal.inc(5); // Increment by a given value

Gauge

Gauges are a metric that can go up or down (e.g., memory usage, number of active users).

const { Gauge } = require('prom-client');
const memoryUsageGauge = new Gauge({
  name: 'memory_usage_bytes',
  help: 'Memory usage in bytes'
});

memoryUsageGauge.set(process.memoryUsage().heapUsed); // Set to current heap used

Histogram

Histograms track the size and number of events in buckets (e.g., request durations or response sizes).

const { Histogram } = require('prom-client');
const httpRequestDuration = new Histogram({
  name: 'http_request_duration_seconds',
  help: 'Duration of HTTP requests in seconds',
  buckets: [0.1, 0.2, 0.5, 1, 5]
});

httpRequestDuration.observe(0.4); // Observe a value in seconds

Summary

Summaries calculate percentiles of observed values (e.g., long-tail request durations).

const { Summary } = require('prom-client');
const httpRequestDurationSummary = new Summary({
  name: 'http_request_duration_summary',
  help: 'Summary of HTTP request durations',
  percentiles: [0.5, 0.9, 0.99]
});

httpRequestDurationSummary.observe(0.3); // Observe a value in seconds

Default Metrics

Collect default metrics from Node.js runtime and system, such as CPU usage, event loop lag, etc.

const { collectDefaultMetrics } = require('prom-client');
collectDefaultMetrics();

Other packages similar to prom-client

metrics-client

This package is similar to prom-client in that it provides a way to collect and expose metrics for monitoring purposes. However, it is not specifically tied to Prometheus and can be used with other monitoring tools.

appmetrics-prometheus

This package is a Prometheus monitoring and metrics exporter for Node.js applications. It is similar to prom-client but is built on top of the appmetrics library, which provides additional insights into the Node.js runtime.

express-prom-bundle

This package is an Express middleware that automatically records request durations and exposes them in Prometheus format. It is similar to prom-client but is more focused on Express applications and provides out-of-the-box middleware for easy integration.

README

Prometheus client for node.js

A prometheus client for node.js that supports histogram, summaries, gauges and counters.

Usage

See example folder for a sample usage. The library does not bundle any web framework, to expose the metrics just return the metrics() function in the registry.

API

Configuration

All metric types has 2 mandatory parameters, name and help.

Default metrics

There are some default metrics recommended by Prometheus itself. These metrics are collected automatically for you when you do require('prom-client').

NOTE: Some of the metrics, concerning File Descriptors and Memory, are only available on Linux.

In addition, some Node-specific metrics are included, such as event loop lag, and active handles. See what metrics there are in lib/metrics.

The function returned from defaultMetrics takes 2 options, a blacklist of metrics to skip, and a timeout for how often the probe should be fired. By default all probes are launched every 10 seconds, but this can be modified like this:

var client = require('prom-client');

var defaultMetrics = client.defaultMetrics;

// Skip `osMemoryHeap` probe, and probe every 5th second.
defaultMetrics(['osMemoryHeap'], 5000);

You can get the full list of metrics by inspecting client.defaultMetrics.metricsList.

defaultMetrics returns an identification when invoked, which is a reference to the Timer used to keep the probes going. This can be passed to clearInterval in order to stop all probes.

NOTE: Existing intervals are automatically cleared when calling defaultMetrics.

var client = require('prom-client');

var defaultMetrics = client.defaultMetrics;

var interval = defaultMetrics();

// ... some time later

clearInterval(interval);

NOTE: unref is called on the interval internally, so it will not keep your node process going indefinitely if it's the only thing keeping it from shutting down.

Disabling default metrics

To disable collecting the default metrics, you have to call the function and pass it to clearInterval.

var client = require('prom-client');

clearInterval(client.defaultMetrics());

// Clear the register
client.register.clear();

Counter

Counters go up, and reset when the process restarts.

var client = require('prom-client');
var counter = new client.Counter('metric_name', 'metric_help');
counter.inc(); // Inc with 1
counter.inc(10); // Inc with 10

Gauge

Gauges are similar to Counters but Gauges value can be decreased.

var client = require('prom-client');
var gauge = new client.Gauge('metric_name', 'metric_help');
gauge.set(10); // Set to 10
gauge.inc(); // Inc with 1
gauge.inc(10); // Inc with 10
gauge.dec(); // Dec with 1
gauge.dec(10); // Dec with 10

There are some utilities for common use cases:

gauge.setToCurrentTime(); // Sets value to current time

var end = gauge.startTimer();
xhrRequest(function(err, res) {
	end(); // Sets value to xhrRequests duration in seconds
});

Histogram

Histograms track sizes and frequency of events.

Configuration

The defaults buckets are intended to cover usual web/rpc requests, this can however be overriden.

var client = require('prom-client');
new client.Histogram('metric_name', 'metric_help', {
	buckets: [ 0.10, 5, 15, 50, 100, 500 ]
});

Examples

var client = require('prom-client');
var histogram = new client.Histogram('metric_name', 'metric_help');
histogram.observe(10); // Observe value in histogram

Utility to observe request durations

var end = histogram.startTimer();
xhrRequest(function(err, res) {
	end(); // Observes the value to xhrRequests duration in seconds
});

Summary

Summaries calculate percentiles of observed values.

Configuration

The default percentiles are: 0.01, 0.05, 0.5, 0.9, 0.95, 0.99, 0.999. But they can be overriden like this:

var client = require('prom-client');
new client.Summary('metric_name', 'metric_help', {
	percentiles: [ 0.01, 0.1, 0.9, 0.99 ]
});

Usage example

var client = require('prom-client');
var summary = new client.Summary('metric_name', 'metric_help');
summary.observe(10);

Utility to observe request durations

var end = summary.startTimer();
xhrRequest(function(err, res) {
	end(); // Observes the value to xhrRequests duration in seconds
});

Labels

All metrics take an array as 3rd parameter that should include all supported label keys. There are 2 ways to add values to the labels

var client = require('prom-client');
var gauge = new client.Gauge('metric_name', 'metric_help', [ 'method', 'statusCode' ]);

gauge.set({ method: 'GET', statusCode: '200' }, 100); // 1st version, Set value 100 with method set to GET and statusCode to 200
gauge.labels('GET', '200').set(100); // 2nd version, Same as above

It is also possible to use timers with labels, both before and after the timer is created:

var end = startTimer({ method: 'GET' }); // Set method to GET, we don't know statusCode yet
xhrRequest(function(err, res) {
	if (err) {
		end({ statusCode: '500' }); // Sets value to xhrRequest duration in seconds with statusCode 500
	} else {
		end({ statusCode: '200' }); // Sets value to xhrRequest duration in seconds with statusCode 200
	}
});

Pushgateway

It is possible to push metrics via a Pushgateway.

var client = require('prom-client');
var gateway = new client.Pushgateway('127.0.0.1:9091');

gateway.pushAdd({ jobName: 'test' }, function(err, resp, body) { }); //Add metric and overwrite old ones
gateway.push({ jobName: 'test' }, function(err, resp, body) { }); //Overwrite all metrics (use PUT)
gateway.delete({ jobName: 'test' }, function(err, resp, body) { }); //Delete all metrics for jobName

//All gateway requests can have groupings on it
gateway.pushAdd({ jobName: 'test', groupings: { key: 'value' } }, function(err, resp, body) { });

Utilites

For convenience, there are 2 bucket generator functions - linear and exponential.

var client = require('prom-client');
new client.Histogram('metric_name', 'metric_help', {
	buckets: client.linearBuckets(0, 10, 20) //Create 20 buckets, starting on 0 and a width of 10
});

new client.Histogram('metric_name', 'metric_help', {
	buckets: client.exponentialBuckets(1, 2, 5) //Create 5 buckets, starting on 1 and with a factor of 2
});

Changelog

[14.1.0] - 2022-08-23

Changed

• types: converted all the generic Metric types to be optional

• The done() functions returned by gauge.startTimer() and summary.startTimer() now return the timed duration. Histograms already had this behavior.

• types: fixed type for registry.getMetricsAsArray()

• Improve performance of gague.inc() and gauge.dec() by calling hashObject() once.

Added

• The processResources metric was added, which keeps a track of all sorts of active resources. It consists of the following gauges:

  • nodejs_active_resources - Number of active resources that are currently keeping the event loop alive, grouped by async resource type.
  • nodejs_active_resources_total - Total number of active resources. It is supposed to provide the combined result of the processHandles and processRequests metrics along with information about any other types of async resources that these metrics do not keep a track of (like timers).

• Support gzipped pushgateway requests