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

Register

You can get all metrics by running register.metrics(), which will output a string for prometheus to consume.

Getting a single metric

If you need to get a reference to a previously registered metric, you can use register.getSingleMetric(*name of metric*).

Removing metrics

You can remove all metrics by calling register.clear(). You can also remove a single metric by calling register.removeSingleMetric(*name of metric*).

Pushgateway

It is possible to push metrics via a Pushgateway.

var client = require('prom-client');
var gateway = new client.Pushgateway('http://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
});

Garbage Collection

To avoid dependencies in this module, GC stats are kept outside of it. If you want GC stats, you can use https://github.com/SimenB/node-prometheus-gc-stats

matrix-org / prom-client