Metrics #

The metrics of one application: declares custom metrics and renders all of them in the Prometheus text format.

import { Metrics } from 'kuzzle-prometheus';

Get it from createMetrics in a Node.js service, or from prometheus.metrics in a Kuzzle application. An application has one instance.

Properties #

commonLabels #

get commonLabels(): Readonly<Record<string, string>>

Labels added to every metric of this instance: the common labels that have a value and, in a Kuzzle application, nodeId and the configured labels.

prefix #

readonly prefix: string

Prepended to the name of every custom metric.

maxLabelSets #

readonly maxLabelSets: number

Label combinations accepted per metric before new ones are dropped (see Keep labels bounded).

handler #

readonly handler: (request: IncomingMessage, response: ServerResponse) => void

A Node.js http / Express handler that answers with render(), whatever the path. If rendering fails, it answers 500 and logs a warning.

http.createServer(metrics.handler).listen(9464);
app.get('/metrics', metrics.handler); // Express

Methods #

Declaration methods throw when the configuration breaks a naming rule or when the name is already declared. Declare each metric once, at startup, and keep the returned object.

counter #

counter<L extends string>(configuration: MetricConfiguration<L>): Counter<L>

Declares a counter. Its name must end with _total.

configuration: see MetricConfiguration.
Returns a Counter.

const errors = metrics.counter({
  name: 'decode_errors_total',
  help: 'Payloads that could not be decoded',
  labelNames: ['protocol'],
});

errors.inc({ protocol: 'mqtt' });

gauge #

gauge<L extends string>(configuration: GaugeConfiguration<L>): Gauge<L>

Declares a gauge, optionally set at scrape time by a collect callback.

configuration: see GaugeConfiguration.
Returns a Gauge.

metrics.gauge({
  name: 'broker_connected',
  help: 'Whether the broker connection is up (1) or not (0)',
  collect: (gauge) => gauge.set(broker.isConnected() ? 1 : 0),
});

histogram #

histogram<L extends string>(configuration: HistogramConfiguration<L>): Histogram<L>

Declares a histogram.

configuration: see HistogramConfiguration.
Returns a Histogram.

const duration = metrics.histogram({
  name: 'decode_duration_seconds',
  help: 'Time to decode a payload',
  buckets: [0.001, 0.005, 0.01, 0.05, 0.1, 0.5],
});

const stop = duration.startTimer();
decode(payload);
stop();

render #

render(): Promise<RenderedMetrics>

Runs the collect callbacks of the gauges, then renders every metric of this instance in the Prometheus text format.

Returns a RenderedMetrics object:

Property	Type	Description
`contentType`	`string`	the `Content-Type` header to answer with
`body`	`string`	the metrics, in the Prometheus text format

fastify.get('/metrics', async (_request, reply) => {
  const { contentType, body } = await metrics.render();
  return reply.type(contentType).send(body);
});