@metrics/prometheus-consumer

A prometheus based streaming consumer for metric streams.

How it works

This module understands metric streams generated by @metrics/client and makes opinionated (but overridable) decisions about how to create prometheus metrics from them.

The prom-client module is required to gather the metrics. It must be passed in as a constructor option (see below).

Additionally, Prometheus expects that your app serve a metrics scraping page. Refer to the prom-client module for details.

For apps using express, this would look like:

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

app.get('/_/metrics', (req, res) => {
    res.set('Content-Type', register.contentType).end(register.metrics());
});

An Example.

Given a metric with a time value:

{
    name: 'my_metric_with_time',
    description: 'Metric that measures time',
    time: 1231432423
}

@metrics/prometheus-consumer will either create a new prometheus Histogram for my_metric_with_time or update one if it already exists.

Usage

Step 1.

Create a new instance of @metrics/prometheus-consumer to be our metrics consumer.

const promClient = require('prom-client');
const metricsConsumer = new PrometheusConsumer({ client: promClient });

Step 2.

Pipe the metrics output stream directly into our consumer making sure to add an error handler to avoid uncaught exceptions.

const client = new MetricsClient();

metricsConsumer.on('error', err => console.error(err));

client.pipe(metricsConsumer);

Step 3.

Render a metrics page for prometheus to scrape. In this example we use express (though any framework will work) to render out metrics on the route /metrics.

app.get('/metrics', (req, res) => {
    res.set('Content-Type', metricsConsumer.contentType()).send(
        metricsConsumer.metrics(),
    );
});

API

• constructor
  • override
  • metrics
  • contentType

constructor(options)

Create a new metrics consumer instance ready to have metrics piped into it.

Examples

const consumer = new PrometheusConsumer({ client: promClient });

remember to add an error handler to the consumer to avoid uncaught exception errors.

consumer.on('error', err => console.error(err));

options

client

Prom client module dependency. Passed in this way in order to avoid having a hard dependency on a specific version of prom-client.

Example

const consumer = new PrometheusConsumer({ client: promClient });

bucketStepStart

Value to start bucket generation from. Each step increases from here by bucketStepFactor

Example

const consumer = new PrometheusConsumer({ bucketStepStart: 1 });

bucketStepFactor

Scaling factor for bucket creation. Must be > 1

Example

const consumer = new PrometheusConsumer({ bucketStepFactor: 2 });

bucketStepCount

Number of times bucketStepFactor should be applied to bucketStepStart

Example

const consumer = new PrometheusConsumer({ bucketStepCount: 8 });

.override(name, config)

Override handling of a specific metric (by name). This is useful if the defaults do not produce the desired result for a given metric. You can change what type of prometheus metrics are generated by setting type and for histograms, you can override bucket handling.

name

An alpha-numeric (plus the underscore character) string name of metric to be overriden. Any metrics that match this name will be processed using the override config (see below)

config

buckets

Example

Override a specific time based metric to only be handled as a counter.

consumer.override('my_time_based_metric', { type: 'counter' });

Example

Override labels for a metric.

consumer.override('my_time_based_metric', {
    labels: ['url', 'method'],
});

Example

Override buckets for a specific time based metric.

consumer.override('my_time_based_metric', {
    buckets: {
        bucketStepStart: 1,
        bucketStepFactor: 2,
        bucketStepCount: 8,
    },
});

.metrics()

Returns the generated metrics text ready for scraping by prometheus. This should be used in conjunction with .contentType()

Example

app.get('/metrics', (req, res) => {
    res.set('Content-Type', metricsConsumer.contentType()).send(
        metricsConsumer.metrics(),
    );
});

.contentType()

Returns the correct content type to use when rendering metrics text for scraping by prometheus. See .metrics() for an express js usage example.