Prometheus client for Node.js

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

Installation

npm install @prometheus-io/client

This package was previously published as prom-client. See the CHANGELOG for the breaking changes involved in upgrading.

API

See example folder for a sample usage. The library does not bundle any web framework. To expose the metrics, respond to Prometheus's scrape requests with the result of await registry.metrics().

Default metrics

There are some default metrics recommended by Prometheus itself. To collect these, call collectDefaultMetrics. In addition, some Node.js-specific metrics are included, such as event loop lag, active handles, GC and Node.js version. See lib/metrics for a list of all metrics.

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

collectDefaultMetrics optionally accepts a config object with following entries:

• prefix an optional prefix for metric names. Default: no prefix.
• register to which registry the metrics should be registered. Default: the global default registry.
• gcDurationBuckets with custom buckets for GC duration histogram. Default buckets of GC duration histogram are [0.001, 0.01, 0.1, 1, 2, 5] (in seconds).
• eventLoopMonitoringPrecision with sampling rate in milliseconds. Must be greater than zero. Default: 10.
• eventLoopUtilizationTimeout interval in milliseconds to calculate event loop utilization. Must be greater than zero. Default: 100.
• eventLoopUtilizationBuckets with custom buckets for the event loop utilization histogram. Default buckets are [0.01, 0.05, 0.1, 0.25, 0.5, 0.6, 0.7, 0.75, 0.8, 0.9, 0.95, 0.99, 1].
• eventLoopUtilizationPercentiles with custom percentiles for the event loop utilization summary. Default percentiles are [0.01, 0.05, 0.5, 0.9, 0.95, 0.99, 0.999].
• eventLoopUtilizationMaxAgeSeconds summary sliding window time in seconds. Must be greater than zero. Default: 60.
• eventLoopUtilizationAgeBuckets summary sliding window buckets. Must be greater than zero. Default: 5.

To register metrics to another registry, pass it in as register:

const client = require('@prometheus-io/client');
const collectDefaultMetrics = client.collectDefaultMetrics;
const Registry = client.Registry;
const register = new Registry();
collectDefaultMetrics({ register });

To use custom buckets for GC duration histogram, pass it in as gcDurationBuckets:

const client = require('@prometheus-io/client');
const collectDefaultMetrics = client.collectDefaultMetrics;
collectDefaultMetrics({ gcDurationBuckets: [0.1, 0.2, 0.3] });

To prefix metric names with your own arbitrary string, pass in a prefix:

const client = require('@prometheus-io/client');
const collectDefaultMetrics = client.collectDefaultMetrics;
const prefix = 'my_application_';
collectDefaultMetrics({ prefix });

To apply generic labels to all default metrics, pass an object to the labels property (useful if you're working in a clustered environment):

const client = require('@prometheus-io/client');
const collectDefaultMetrics = client.collectDefaultMetrics;
collectDefaultMetrics({
  labels: { NODE_APP_INSTANCE: process.env.NODE_APP_INSTANCE },
});

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

Default metrics are collected on scrape of metrics endpoint, not on an interval.

const client = require('@prometheus-io/client');

const collectDefaultMetrics = client.collectDefaultMetrics;

collectDefaultMetrics();

Custom Metrics

All metric types have two mandatory parameters: name and help. Refer to for guidance on naming metrics.

For metrics based on point-in-time observations (e.g. current memory usage, as opposed to HTTP request durations observed continuously in a histogram), you should provide a collect() function, which will be invoked when Prometheus scrapes your metrics endpoint. collect() can either be synchronous or return a promise. See Gauge below for an example. (Note that you should not update metric values in a setInterval callback; do so in this collect function instead.)

See Labels for information on how to configure labels for all metric types.

Counter

Counters go up, and reset when the process restarts.

const client = require('@prometheus-io/client');
const counter = new client.Counter({
  name: 'metric_name',
  help: 'metric_help',
});
counter.inc(); // Increment by 1
counter.inc(10); // Increment by 10

Gauge

Gauges are similar to Counters but a Gauge's value can be decreased.

const client = require('@prometheus-io/client');
const gauge = new client.Gauge({ name: 'metric_name', help: 'metric_help' });
gauge.set(10); // Set to 10
gauge.inc(); // Increment 1
gauge.inc(10); // Increment 10
gauge.dec(); // Decrement by 1
gauge.dec(10); // Decrement by 10

Configuration

If the gauge is used for a point-in-time observation, you should provide a collect function:

const client = require('@prometheus-io/client');
new client.Gauge({
  name: 'metric_name',
  help: 'metric_help',
  collect() {
    // Invoked when the registry collects its metrics' values.
    // This can be synchronous or it can return a promise/be an async function.
    this.set(/* the current value */);
  },
});

// Async version:
const client = require('@prometheus-io/client');
new client.Gauge({
  name: 'metric_name',
  help: 'metric_help',
  async collect() {
    // Invoked when the registry collects its metrics' values.
    const currentValue = await somethingAsync();
    this.set(currentValue);
  },
});

Note that you should not use arrow functions for collect because arrow functions will not have the correct value for this.

Utility Functions

// Set value to current time in seconds:
gauge.setToCurrentTime();

// Record durations:
const end = gauge.startTimer();
http.get('url', res => {
  end();
});

Histogram

Histograms track sizes and frequency of events.

Configuration

The defaults buckets are intended to cover usual web/RPC requests, but they can be overridden. (See also Bucket Generators.)

const client = require('@prometheus-io/client');
new client.Histogram({
  name: 'metric_name',
  help: 'metric_help',
  buckets: [0.1, 5, 15, 50, 100, 500],
});

Examples

const client = require('@prometheus-io/client');
const histogram = new client.Histogram({
  name: 'metric_name',
  help: 'metric_help',
});
histogram.observe(10); // Observe value in histogram

Utility Methods

const end = histogram.startTimer();
xhrRequest(function (err, res) {
  const seconds = end(); // Observes and returns 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 overridden by specifying a percentiles array. (See also Bucket Generators.)

const client = require('@prometheus-io/client');
new client.Summary({
  name: 'metric_name',
  help: 'metric_help',
  percentiles: [0.01, 0.1, 0.9, 0.99],
});

To enable the sliding window functionality for summaries you need to add maxAgeSeconds and ageBuckets to the config like this:

const client = require('@prometheus-io/client');
new client.Summary({
  name: 'metric_name',
  help: 'metric_help',
  maxAgeSeconds: 600,
  ageBuckets: 5,
  pruneAgedBuckets: false,
});

The maxAgeSeconds will tell how old a bucket can be before it is reset and ageBuckets configures how many buckets we will have in our sliding window for the summary. If pruneAgedBuckets is false (default), the metric value will always be present, even when empty (its percentile values will be 0). Set pruneAgedBuckets to true if you don't want to export it when it is empty.

Examples

const client = require('@prometheus-io/client');
const summary = new client.Summary({
  name: 'metric_name',
  help: 'metr