promjs-plus

A Prometheus metrics registry implemented in TypeScript. Zero dependencies, ~5KB, runs in Node.js, browsers, and Cloudflare Workers.

Forked from weaveworks/promjs (deprecated).

Features

• Zero dependencies - runs anywhere JavaScript runs
• Fast - optimized for high-throughput metrics collection
• Edge-ready - works in Cloudflare Workers, Deno, browsers
• TypeScript - full type safety
• Prometheus-compliant - follows client best practices

Installation

Install via npm:

$ npm install --save promjs-plus

Usage

// Using es6 imports
import prom from 'promjs-plus';
// Using CommonJS
const prom = require('promjs-plus');

const registry = prom();
const pageRequestCounter = registry.create('counter', 'page_requests', 'A counter for page requests');

pageRequestCounter.inc();
console.log(registry.metrics());
// =>
// # HELP page_requests A counter for page requests \n
// # TYPE page_requests counter
// page_requests 1 \n

API

prom()

Returns a registry class.

Registry

new Registry([options]) => registry

Creates a new registry. Optionally pass default labels that will be applied to all metrics.

import { Registry } from 'promjs-plus';

const registry = new Registry({ defaultLabels: { env: 'production', region: 'us-east-1' } });

registry.create(type, name, help) => collector (counter | gauge | histogram)

Returns a metric class of the specified type. The metric is already registered with the registry that creates it.

Arguments

1. type (String): The type of metric to create. The current supported types are counter, gauge, and histogram.
2. name (String): The name of the metric
3. help (String): The help message for the metric

Example

import prom from 'promjs-plus';

const registry = prom();
const counter = registry.create('counter', 'my_counter', 'A counter for things');

registry.setDefaultLabels(labels) => self

Sets default labels applied to all metrics in output. Metric-level labels override defaults.

registry.getDefaultLabels() => object

Returns a copy of the current default labels.

registry.metrics([options]) => string

Returns a prometheus formatted string containing all existing metrics.

Options:

• format (String): Output format. Either 'prometheus' (default) or 'openmetrics'. OpenMetrics format appends # EOF to the output.

const counter = registry.create('counter', 'my_counter', 'A counter for things');
counter.inc();

console.log(registry.metrics());
// =>
// # HELP my_counter A counter for things
// # TYPE my_counter counter
// my_counter 1

console.log(registry.metrics({ format: 'openmetrics' }));
// =>
// # HELP my_counter A counter for things
// # TYPE my_counter counter
// my_counter 1
// # EOF

registry.clear() => self

Removes all metrics from internal data storage. Returns itself to allow for chaining.

registry.reset() => self

Resets all existing metrics to 0. This can be used to reset metrics after reporting to a prometheus aggregator. Returns itself to allow for chaining.

registry.get(type, name) => collector (counter | gauge | histogram) | null

Fetches an existing metric by name. Returns null if no metrics are found

Collector

All of the metric classes (Counter, Gauge, Histogram) inherit from the Collector class. Collector methods are available on each of the metic classes.

collector.reset([labels]) => self

Resets metrics in the collector. Optionally pass in labels to reset only those labels.

collector.resetAll() => self

Resets all metrics in the collector, including metrics with labels.

Counter

A counter can only ever be incremented positively.

counter.inc([labels]) => self

Increments a counter. Optionally pass in a set of labels to increment only those labels.

counter.add(amount, [labels]) => self

Increments a counter by a given amount. amount must be a Number. Optionally pass in a set of labels to increment only those labels.

const counter = registry.create('counter', 'my_counter', 'A counter for things');
counter.inc();
counter.add(2, { ok: true, status: 'success', code: 200 });
counter.add(2, { ok: false, status: 'fail', code: 403 });

console.log(registry.metrics());
// =>
// # HELP my_counter A counter for things
// # TYPE my_counter counter
// my_counter 1
// my_counter{ok="true",status="success",code="200"} 2
// my_counter{ok="false",status="fail",code="403"} 2

Gauge

A gauge is similar to a counter, but can be incremented up and down.

gauge.inc([labels]) => self

Increments a gauge by 1.

gauge.dec([lables]) => self

Decrements a gauge by 1.

gauge.add(amount, [lables]) => self

Increments a gauge by a given amount. amount must be a Number.

gauge.sub(amount, [labels]) => self

Decrements a gauge by a given amount.

const gauge = registry.create('gauge', 'my_gauge', 'A gauge for stuffs');
gauge.inc();
gauge.inc({ instance: 'some_instance' });
gauge.dec({ instance: 'some_instance' });
gauge.add(100, { instance: 'some_instance' });
gauge.sub(50, { instance: 'some_instance' });

console.log(registry.metrics());
// =>
// # HELP my_gauge A gauge for stuffs
// # TYPE my_gauge gauge
// my_gauge 1
// my_gauge{instance="some_instance"} 50

Histogram

Histograms are used to group values into pre-defined buckets. Buckets are passed in to the registry.create() call.

Bucket Helpers

Two helper functions are available for generating bucket boundaries:

import { linearBuckets, exponentialBuckets } from 'promjs-plus';

// linearBuckets(start, width, count) => number[]
linearBuckets(0, 10, 5);      // [0, 10, 20, 30, 40]

// exponentialBuckets(start, factor, count) => number[]
exponentialBuckets(1, 2, 5);  // [1, 2, 4, 8, 16]

// Use with histogram
const histogram = registry.create('histogram', 'request_duration_ms', 'Request duration', 
  exponentialBuckets(1, 2, 10)  // 1, 2, 4, 8, 16, 32, 64, 128, 256, 512ms
);

histogram.observe(value) => self

Adds value to a pre-existing bucket.value must be a number.

const histogram = registry.create('histogram', 'response_time', 'The response time', [
  200,
  300,
  400,
  500
]);
histogram.observe(199);
histogram.observe(299);
histogram.observe(450);

console.log(registry.metrics());
// =>
// # HELP response_time The response time
// # TYPE response_time histogram
// response_time_count 3
// response_time_sum 948
// response_time_bucket{le="200"} 1
// response_time_bucket{le="300"} 2
// response_time_bucket{le="400"} 2
// response_time_bucket{le="500"} 3
// response_time_bucket{le="+Inf"} 3

Constants

Content-Type headers for HTTP responses:

import { PROMETHEUS_CONTENT_TYPE, OPENMETRICS_CONTENT_TYPE } from 'promjs-plus';

// PROMETHEUS_CONTENT_TYPE = 'text/plain; version=0.0.4'
// OPENMETRICS_CONTENT_TYPE = 'application/openmetrics-text; version=1.0.0'

Getting Help

If you have any questions about, feedback for or problems with promjs-plus:

• File an issue.