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.
To collect these, call collectDefaultMetrics
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, active handles and Node.js version. See what metrics there are in
lib/metrics.
The function returned from collectDefaultMetrics
takes 1 option, a timeout for how often the probe should
be fired. By default probes are launched every 10 seconds, but this can be modified like this:
var client = require('prom-client');
var collectDefaultMetrics = client.collectDefaultMetrics;
collectDefaultMetrics(5000);
You can get the full list of metrics by inspecting client.collectDefaultMetrics.metricsList
.
collectDefaultMetrics
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 collectDefaultMetrics
.
var client = require('prom-client');
var collectDefaultMetrics = client.collectDefaultMetrics;
var interval = collectDefaultMetrics();
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.
Stop polling default metrics
To stop collecting the default metrics, you have to call the function and pass it to clearInterval
.
var client = require('prom-client');
clearInterval(client.collectDefaultMetrics());
client.register.clear();
Counter
Counters go up, and reset when the process restarts.
var client = require('prom-client');
var counter = new client.Counter({ name: 'metric_name', help: 'metric_help' });
counter.inc();
counter.inc(10);
Gauge
Gauges are similar to Counters but Gauges value can be decreased.
var client = require('prom-client');
var gauge = new client.Gauge({ name: 'metric_name', help: 'metric_help' });
gauge.set(10);
gauge.inc();
gauge.inc(10);
gauge.dec();
gauge.dec(10);
There are some utilities for common use cases:
gauge.setToCurrentTime();
var end = gauge.startTimer();
xhrRequest(function(err, res) {
end();
});
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({ name: 'metric_name', help: 'metric_help', buckets: [ 0.10, 5, 15, 50, 100, 500 ] });
You can include all label names as a property as well.
var client = require('prom-client');
new client.Histogram({ name: 'metric_name', help: 'metric_help', labelNames: [ 'status_code' ], buckets: [ 0.10, 5, 15, 50, 100, 500 ] });
Examples
var client = require('prom-client');
var histogram = new client.Histogram({ name: 'metric_name', help: 'metric_help' });
histogram.observe(10);
Utility to observe request durations
var end = histogram.startTimer();
xhrRequest(function(err, res) {
end();
});
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({ name: 'metric_name', help: 'metric_help', percentiles: [ 0.01, 0.1, 0.9, 0.99 ] });
Usage example
var client = require('prom-client');
var summary = new client.Summary({ name: 'metric_name', help: 'metric_help' });
summary.observe(10);
Utility to observe request durations
var end = summary.startTimer();
xhrRequest(function(err, res) {
end();
});
Labels
All metrics can take a labelNames property in the configuration object. All labelNames that the metric support needs to be declared here. There are 2 ways to add values to the labels
var client = require('prom-client');
var gauge = new client.Gauge({ name: 'metric_name', help: 'metric_help', labelNames: [ 'method', 'statusCode' ] });
gauge.set({ method: 'GET', statusCode: '200' }, 100);
gauge.labels('GET', '200').set(100);
It is also possible to use timers with labels, both before and after the timer is created:
var end = startTimer({ method: 'GET' });
xhrRequest(function(err, res) {
if (err) {
end({ statusCode: '500' });
} else {
end({ statusCode: '200' });
}
});
Timestamps
Counter and gauge metrics can take a timestamp argument after the value argument.
This argument must be a Date or a number (milliseconds since Unix epoch, i.e. 1970-01-01 00:00:00 UTC, excluding leap seconds).
gauge.set(100, 1485531442231);
gauge.set(100, Date.now());
gauge.set(100, new Date());
gauge.set({ method: 'GET', statusCode: '200' }, 100, new Date());
gauge.labels('GET', '200').set(100, new Date());
counter.inc(1, new Date());
Multiple registries
By default, metrics are automatically registered to the global registry (located at require('prom-client').register
).
You can prevent this by setting last parameter when creating the metric to false
(depending on metric, this might be 4th or 5th parameter).
Using non-global registries requires creating Registry instance and adding it inside registers
inside the configuration object. Alternatively
you can pass an empty registers
array and register it manually.
var client = require('prom-client');
var registry = new client.Registry();
var counter = new client.Counter({name: 'metric_name', help: 'metric_help', registers: [ registry ]});
var histogram = new client.Histogram({name: 'metric_name', help: 'metric_help', registers: [ ]});
registry.registerMetric(histogram);
counter.inc();
Register
You can get all metrics by running register.metrics()
, which will output a string for prometheus to consume.
Geting a single metric for Prometheus displaying
If you need to output a single metric for Prometheus, you can use register.getSingleMetricAsString(*name of metric*)
, it 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) { });
gateway.push({ jobName: 'test' }, function(err, resp, body) { });
gateway.delete({ jobName: 'test' }, function(err, resp, body) { });
gateway.pushAdd({ jobName: 'test', groupings: { key: 'value' } }, function(err, resp, body) { });
gateway = new client.Pushgateway('http://127.0.0.1:9091', { timeout: 5000 });
Utilites
For convenience, there are 2 bucket generator functions - linear and exponential.
var client = require('prom-client');
new client.Histogram({
name: 'metric_name',
help: 'metric_help',
buckets: client.linearBuckets(0, 10, 20)
});
new client.Histogram({
name: 'metric_name',
help: 'metric_help',
buckets: client.exponentialBuckets(1, 2, 5)
});
The content-type prometheus expects is also exported as a constant, both on the register
and from the main file of this project, called contentType
.
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