Node Actuator Lite

Spring Boot Actuator, for Node.js. Production health checks, Prometheus metrics, environment inspection, thread and heap dumps, and runtime log-level changes — one runtime dependency, and a dashboard you can open in a browser.

npm install node-actuator-lite

import express from 'express';
import { actuatorMiddleware } from 'node-actuator-lite';

const app = express();
app.use(actuatorMiddleware().handler);

app.listen(3000); // every /actuator/* endpoint is now live

That is the entire setup. Requires Node.js 18 or newer, works with both require and import, and pulls in exactly one runtime dependency (prom-client).

The dashboard is the part you can't get elsewhere

GET /actuator/dashboard serves that page from the library itself — a single HTML document with inline CSS and JS, no CDN calls, no build step, no external assets. It auto-refreshes every five seconds and pauses when the tab is backgrounded. Useful for eyeballing a service long before you stand up Grafana.

Three things you can do that most health-check libraries don't

Change a log level in production without redeploying.

curl -X POST http://localhost:8081/actuator/loggers/ROOT \
  -H 'Content-Type: application/json' -d '{"configuredLevel":"DEBUG"}'

Adapters ship for Pino, Winston, and Bunyan.

Take a heap snapshot over HTTP, streamed to disk without blocking the event loop, throttled to one per minute. Open the result in Chrome DevTools → Memory → Load.

curl -X POST http://localhost:8081/actuator/heapdump

Inspect the environment safely. GET /actuator/env returns Spring-style property sources with secrets masked. Connection strings keep their host and database name visible and mask only the password, so postgres://app:hunter2@db:5432/orders reads back as postgres://app:******@db:5432/orders.

How it compares

| | node-actuator-lite | @godaddy/terminus | lightship | express-actuator | | ---------------------------------- | :----------------: | :---------------: | :-------: | :--------------: | | Health checks | Yes | Yes | Yes | Yes | | Kubernetes liveness / readiness | Yes | Yes | Yes | — | | Prometheus endpoint | Yes | — | — | — | | Environment inspection with masking| Yes | — | — | — | | Thread / event-loop dump | Yes | — | — | — | | Heap dump over HTTP | Yes | — | — | — | | Runtime log-level changes | Yes | — | — | — | | Built-in dashboard | Yes | — | — | — | | Graceful shutdown | — | Yes | Yes | — | | Framework support | Express, Fastify, Koa, node:http, serverless | Any http server | Any | Express only | | Runtime dependencies | 1 | 1 | 4 | 2 |

If graceful shutdown is the only thing you need, @godaddy/terminus does that one job well and this library does not compete with it — the two compose fine.

Endpoints

All paths are relative to basePath (default /actuator), and each appears in discovery only when enabled.

| Method | Path | Description | |--------|------|-------------| | GET | /actuator | Discovery — lists every enabled endpoint | | GET | /actuator/dashboard | Self-contained HTML dashboard | | GET | /actuator/health | Health check, shallow or deep | | GET | /actuator/health/{component\|group} | One component, or a group such as liveness | | GET | /actuator/info | Build and runtime information | | GET | /actuator/metrics | Process CPU, memory, and uptime as JSON | | GET | /actuator/env | Environment variables, masked | | GET | /actuator/env/{name} | A single environment variable | | GET | /actuator/threaddump | Event loop, active handles, V8 heap, workers | | POST | /actuator/heapdump | Write a V8 heap snapshot to disk | | GET | /actuator/prometheus | Prometheus text exposition format | | GET | /actuator/loggers | List loggers and their levels | | POST | /actuator/loggers/{name} | Change a logger's level at runtime |

Production safety

These endpoints expose operational data, so treat them like any other admin surface. Use the production preset, an auth callback, or both.

import { NodeActuator } from 'node-actuator-lite';

const actuator = new NodeActuator({
  port: 8081,
  preset: 'production',
  auth: ({ raw }) => raw.headers.authorization === `Bearer ${process.env.OPS_TOKEN}`,
  health: {
    groups: { liveness: ['process'], readiness: ['diskSpace', 'database'] },
  },
});

await actuator.start();

The production preset keeps /health (shallow), /info, /metrics, and /prometheus, and disables /env, /threaddump, /heapdump, /loggers, and /dashboard. Individual endpoints can still be re-enabled explicitly.

The preset is never inferred from NODE_ENV. Upgrading this library can't silently disable an endpoint your deployment relies on — if NODE_ENV=production is set without a preset, you get a warning suggesting one, not a behaviour change.

Framework adapters

// Express / Connect
import { actuatorMiddleware } from 'node-actuator-lite';
app.use(actuatorMiddleware().handler);

// Fastify
import { actuatorPlugin } from 'node-actuator-lite';
await app.register(actuatorPlugin);

// Koa
import { actuatorKoa } from 'node-actuator-lite/middleware/koa';
app.use(actuatorKoa().middleware);

// node:http — requests outside basePath fall through to next()
import { actuatorHttp } from 'node-actuator-lite/middleware/http';
http.createServer(actuatorHttp().handler).listen(8080);

In serverless mode no server is started and you call the data methods directly, which suits Vercel and Lambda:

const actuator = new NodeActuator({ serverless: true });

await actuator.getHealth();     // shallow; pass 'always' to force deep
await actuator.getInfoAsync();
await actuator.getPrometheus();
actuator.getMetrics();
actuator.getEnv();

Documentation

• USAGE.md — the full guide: every configuration option, custom health indicators, health groups, masking rules, custom Prometheus metrics, logger adapters, Kubernetes probe specs, and the complete programmatic API.
• examples/ — runnable Express, Fastify, Lambda, and Kubernetes examples.
• src/core/types.ts — the authoritative ActuatorOptions shape.

Ecosystem

Adopt these independently or together:

• node-eventloop-watchdog — detects event-loop stalls and captures stack traces. Registers /actuator/eventloop* automatically when both are installed.
• node-request-trace — per-request timelines without OpenTelemetry.
• node-observability-lite — wires all three together with production-safe presets in one line.

Contributing

CONTRIBUTING.md covers development setup and release checks. Report security issues privately as described in SECURITY.md. Release notes live in CHANGELOG.md.

License

MIT — see LICENSE.