Getting Started #

Kuzzle Prometheus exposes Prometheus metrics from Kuzzle applications and from any Node.js service, with one API and shared labels: one dashboard or alert rule works for every service.

The package has two entry points:

Requirements: Node.js 22.12+ or 24. The Kuzzle entry point requires Kuzzle >=2.59.0 <3.

Which guide do I need? #

In a Kuzzle application #

npm install kuzzle-prometheus

import { Backend } from 'kuzzle';
import { PrometheusPlugin } from 'kuzzle-prometheus/kuzzle';

const app = new Backend('my-app');

const prometheus = new PrometheusPlugin();
app.plugin.use(prometheus);

app.start();

Once Kuzzle has started, the metrics are served at GET /_metrics?format=prometheus:

curl "http://localhost:7512/_metrics?format=prometheus"

The Kuzzle plugin guide covers the routes, access rights, configuration and application metrics.

In a Node.js service #

1. Install #

npm install kuzzle-prometheus

2. Create one Metrics instance #

Create it once, at startup, and share it across the service.

// metrics.ts
import { createMetrics } from 'kuzzle-prometheus';

export const metrics = createMetrics({
  service: 'ingestion-gateway',
  prefix: 'gateway_',
});

service names this service in every metric. project and environment usually come from the environment (KUZZLE_PROMETHEUS_PROJECT, KUZZLE_PROMETHEUS_ENVIRONMENT), set by the deployment: see Common labels.

Node.js process metrics (CPU, memory, event loop lag, GC) are collected from this point.

3. Expose /metrics #

Prometheus pulls metrics: the service answers GET /metrics.

With the Node.js http module, on a dedicated port:

import http from 'node:http';
import { metrics } from './metrics';

http.createServer(metrics.handler).listen(9464);

metrics.handler answers every path. To mount it on an existing server, route GET /metrics to it:

// Express
app.get('/metrics', metrics.handler);

// Fastify, or any framework: render() returns the body and its content type
fastify.get('/metrics', async (_request, reply) => {
  const { contentType, body } = await metrics.render();
  return reply.type(contentType).send(body);
});

4. Count what matters #

const processed = metrics.counter({
  name: 'messages_processed_total',
  help: 'Messages processed, by outcome',
  labelNames: ['outcome'],
});

processed.inc({ outcome: 'ok' });

Custom metrics covers gauges, histograms, naming and labels.

5. Check #

curl -s localhost:9464/metrics | grep gateway_

# HELP gateway_messages_processed_total Messages processed, by outcome
# TYPE gateway_messages_processed_total counter
gateway_messages_processed_total{outcome="ok",project="acme",environment="production",service="ingestion-gateway"} 1