fastify-monitor

Self-hosted monitoring plugin for Fastify. Register it to expose a live dashboard, JSON metrics, and optional health checks.

Features

• Works as a Fastify plugin via register()
• /status — lightweight HTML dashboard
• /status/data — JSON snapshot for the UI or automation
• /status/health — aggregate health endpoint when healthChecks are configured
• Process metrics: CPU usage, RSS memory, heap used, event loop delay
• HTTP metrics: response time, RPS, per–status-family totals (2xx–5xx) over the selected span
• External URL health checks with optional timeout
• Optional access control: shared secret via authToken read from either the configured header or the configured query param (authFrom), or a custom authorize function
• Configurable spans (e.g. 1m / 5m / 15m windows) and sampleInterval

Installation

npm install fastify-monitor

Usage

const fastify = require('fastify')({ logger: true });
const fastifyMonitor = require('fastify-monitor');

fastify.register(fastifyMonitor, {
  title: 'Fastify Status',
  path: '/status',
  dataPath: '/status/data',
  healthPath: '/status/health',
  ignoreStartsWith: '/status',
  sampleInterval: 1000,
  spans: [
    { interval: 1, retention: 60 },
    { interval: 5, retention: 60 },
    { interval: 15, retention: 60 }
  ],
  healthChecks: [
    { name: 'users-service', url: 'http://localhost:4000/health', timeoutMs: 1500 },
    'http://localhost:5000/ready'
  ],
  // Optional: protect /status, /status/data, /status/health with a shared secret.
  authToken: 'your-secret',
  authFrom: 'header', // default: only the header is checked (query is ignored)
  authHeaderName: 'x-monitor-key' // curl -H "x-monitor-key: your-secret"
});

fastify.get('/', async () => ({ ok: true }));

fastify.listen({ port: 3000 });

Query-based token (browser-friendly): set authFrom: 'query'. Only the query parameter is checked; a correct header without the query is not accepted. Open the dashboard with the token in the URL, e.g. http://localhost:3000/status?token=your-secret. The page’s polling calls reuse the same query string.

fastify.register(fastifyMonitor, {
  authToken: 'your-secret',
  authFrom: 'query',
  authQueryName: 'token' // default
});

Custom checks: if you pass authorize, it is used instead of authToken (full control over headers, query, session, etc.).

fastify.register(fastifyMonitor, {
  authorize: async (request) => {
    return request.headers['x-api-key'] === process.env.MONITOR_KEY;
  }
});

API

fastify.fastifyMonitor.getSnapshot()

Returns the current monitoring snapshot (same shape as /status/data).

fastify.fastifyMonitor.getSpans()

Returns the internal span buffers used for rolling windows.

Options

| Option | Type | Description | |--------|------|-------------| | title | string | Dashboard page title | | path | string | HTML dashboard route | | dataPath | string | JSON metrics route | | healthPath | string | Health summary route | | ignoreStartsWith | string | Prefix of paths excluded from HTTP response metrics | | sampleInterval | number | Process metric sampling interval in ms | | spans | Array<{ interval, retention }> | interval in seconds, retention = number of points kept per span | | healthChecks | Array<string \| { name, url, timeoutMs }> | URLs to probe (GET); 2xx = ok | | authToken | string | If non-empty, dashboard and health routes require this value. How it is read is controlled by authFrom. Ignored when authorize is set. | | authFrom | 'header' \| 'query' | With authToken: 'header' — only authHeaderName is read (query ignored). 'query' — only authQueryName is read (header ignored). Default 'header'. | | authHeaderName | string | Header name when authFrom is 'header' (default x-monitor-key; Node lowercases header keys on request.headers) | | authQueryName | string | Query parameter name when authFrom is 'query' (default token) | | authorize | function | Optional. (request, reply) => boolean \| Promise<boolean>. When provided, only this runs for access control; authToken is ignored. |

Project layout

• index.js — plugin implementation (routes, collection, embedded dashboard)
• package.json — package metadata and dependencies
• README.md — documentation

Sources & reference libraries

Ideas and patterns were informed by the wider Fastify and Node ecosystem, including:

• fastify-status — minimal plugin registration and health-style routes
• @fastify/under-pressure — health and pressure-related patterns in Fastify
• @immobiliarelabs/fastify-metrics — hook-based request/response observation
• nest-fastify-status-monitor — status UI and real-time monitoring concepts in a Nest/Fastify context

This package is intended to work out of the box when registered on a Fastify instance with sensible defaults.