Skip to content

Metrics ​

Overview ​

The Metrics Module (src/modules/metrics/) exposes runtime and HTTP metrics in Prometheus text format, backed by prom-client. It is disabled by default and, when enabled, is served from a single admin-only endpoint (GET /server/metrics).

The module has two parts:

  • Instrumentation — Fastify hooks (onRequest / onResponse) that observe every request into a set of HTTP metrics.
  • Exposition — the GET /server/metrics endpoint that renders the current registry as Prometheus text.

Enabling Metrics ​

Metrics collection and the endpoint are gated by the METRICS_ENABLED environment variable (default false). When disabled:

  • registerMetricsHooks(app) is a no-op — no hooks are registered and no metrics are collected.
  • GET /server/metrics returns 404 Not Found ({ "error": "Metrics not enabled" }).
VariableDefaultDescription
METRICS_ENABLEDfalseMaster switch. Set to true to register instrumentation hooks and enable the endpoint.
METRICS_NAME_PREFIXodp_Prefix applied to every metric name (both default and HTTP metrics).

Endpoint ​

GET /server/metrics ​

Return the current metrics in Prometheus text format.

Auth required: Yes — admin only (requireAdmin preHandler).

Response 200 — Content-Type: text/plain; version=0.0.4 (from prom-client's registry content type), body is the Prometheus exposition text.

Response 404 — when METRICS_ENABLED is false:

json
{ "error": "Metrics not enabled" }

Collected Metrics ​

All metric names are prefixed with METRICS_NAME_PREFIX (default odp_).

Default runtime metrics ​

prom-client's collectDefaultMetrics({ prefix }) registers the standard Node.js process metrics: CPU usage, resident/heap memory, event-loop lag, garbage collection, active handles/requests, and process start time.

HTTP metrics ​

MetricTypeLabelsDescription
{prefix}http_requests_totalCountermethod, route, status_codeTotal number of HTTP requests processed
{prefix}http_request_duration_secondsHistogrammethod, route, status_codeRequest duration in seconds. Buckets: 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10
{prefix}http_active_connectionsGauge—Requests currently being processed (incremented on onRequest, decremented on onResponse)
{prefix}http_request_size_bytesHistogrammethod, routeSize of request bodies in bytes (from the content-length header). Buckets: 100 … 10_000_000
{prefix}http_response_size_bytesHistogrammethod, route, status_codeSize of response bodies in bytes (from the response content-length header). Buckets: 100 … 10_000_000

Sizes are recorded only when a content-length is present and greater than zero.

Instrumentation ​

registerMetricsHooks(app) is called during server setup (createServer()) and wires two Fastify hooks when METRICS_ENABLED is true:

  • onRequest — stamps a high-resolution start time on the request and increments http_active_connections.
  • onResponse — computes duration from the start time, increments http_requests_total, decrements http_active_connections, and observes request/response sizes.

Route normalisation ​

To avoid high-cardinality labels, the route label is derived by normaliseRoute(), which prefers Fastify's matched route pattern (request.routeOptions.url, e.g. /items/:collection/:pk) over the raw URL. This keeps per-route series bounded regardless of dynamic path parameters. Requests that match no route (404) all get the single label route="unknown_route", never the raw URL, so probing random paths cannot grow the label set.

To ship these metrics to OpenObserve with alerts and a dashboard, see Telemetry.

Programmatic API ​

Exported from src/modules/metrics/index.ts:

ExportPurpose
initMetrics()Lazily and idempotently create the metric instruments and register default metrics.
registerMetricsHooks(app)Register the onRequest / onResponse instrumentation hooks (no-op when disabled).
getMetricsOutput()Return the Prometheus text-format string for the current registry.
getMetricsContentType()Return the registry's content type for the response.
resetMetrics()Clear the registry and reset init state (used in tests).

ODP Internal API Documentation