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, 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.

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
});

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

Changelog

[13.0.0] - 2020-12-16

Breaking

• changed: The following functions are now async (return a promise): registry.metrics() registry.getMetricsAsJSON() registry.getMetricsAsArray() registry.getSingleMetricAsString()

  If your metrics server has a line like res.send(register.metrics()), you should change it to res.send(await register.metrics()).

  Additionally, all metric types now accept an optional collect function, which is called when the metric's value should be collected and within which you should set the metric's value. You should provide a collect function for point-in-time metrics (e.g. current memory usage, as opposed to HTTP request durations that are continuously logged in a histogram).

• changed: register.clusterMetrics() no longer accepts a callback; it only returns a promise.

• removed: v12.0.0 added the undocumented functions registry.registerCollector and registry.collectors(). These have been removed. If you were using them, you should instead provide a collect function as described above.

Changed

• fix: provide nodejs_version_info metric value after calling registry.resetMetrics() (#238)
• fix: provide process_max_fds metric value after calling registry.resetMetrics()
• fix: provide process_start_time_seconds metric value after calling registry.resetMetrics()
• chore: improve performance of registry.getMetricAsPrometheusString
• chore: refactor metrics to reduce code duplication
• chore: replace utils.getPropertiesFromObj with Object.values
• chore: remove unused catch bindings
• chore: upgrade Prettier to 2.x
• fix: startTimer returns number in typescript instead of void
• fix: incorrect typings of `registry.getSingleMetric' (#388)
• chore: stop testing node v13 on CI

Added

• feat: exposed registry.registerCollector() and registry.collectors() methods in TypeScript declaration
• Added: complete working example of a pushgateway push in example/pushgateway.js
• feat: added support for adding labels to default metrics (#374)
• Added CHANGELOG reminder