Observability@rhythmjs/observability
Health & shutdown
Concurrent health indicators behind cached liveness and readiness probes, and a graceful-shutdown sequence that drains before it tears down.
On this page
The health service and module#
@rhythmjs/observability/health is a startup module rather than a middleware. createHealthService(options) builds a HealthService; the options are indicators (the checks below), timeout (per-indicator default, 5000 ms), and cacheTtl (readiness report cache, 1000 ms). healthModule.forRoot(options) is the same service as a Rhythm module: a child app whose startup context holds a healthService, which you pull into your app with include.
import { Rhythm, include } from "@rhythmjs/rhythm";
import { healthModule } from "@rhythmjs/observability/health";
const app = new Rhythm().register(
include(
healthModule.forRoot({
indicators: [
{ name: "db", check: async () => ({ status: (await db.ping()) ? "up" : "down" }) },
{ name: "search", critical: false, timeout: 1000, check: () => search.health() },
],
}),
(health) => ({ healthService: health.healthService }),
),
);Because the module creates its own instance, code outside the request context (healthRoutes, gracefulShutdown) cannot reach it. When you need to hand the service to those, create it yourself with createHealthService and keep the reference, as the sections below do.
Indicators#
A HealthIndicator is { name, check, critical?, timeout? }. check() returns (or resolves to) { status: "up" | "down", details? }. All indicators run concurrently; each races its own timeout (its timeout, else the module default), and a throw or timeout becomes status: "down" with the error message under details.error; a broken check never breaks the endpoint. Every check reports its durationMs.
critical defaults to true: a down critical indicator marks the whole report down. Mark best-effort dependencies critical: false; their status still shows in the report without failing readiness.
Liveness and readiness#
The service exposes the two probe questions separately. live() is synchronous and cannot fail - { status: "up", uptime, timestamp } with uptime in whole seconds, answering "is the process running?". ready() answers "should traffic come here?": it runs the indicators and returns a HealthReport - { status, shuttingDown, checks } keyed by indicator name. Reports are cached for cacheTtl so probe storms and dashboard polling stay cheap; once shutdown() has been called, ready() short-circuits to down with shuttingDown: true and no checks run.
Serving the probes#
healthRoutes(service, { path? }) returns a RhythmRouter (named "health") that you add to the app with mount. Its routes are the full paths ${path}/live and ${path}/ready, with path defaulting to /health; mounting adds no prefix, so use path to relocate them. GET /health/live always answers 200 with the liveness snapshot, and GET /health/ready answers the report with 200 when up and 503 when down; the status code Kubernetes-style readiness probes act on.
import { Rhythm, mount } from "@rhythmjs/rhythm";
import { createHealthService, healthRoutes } from "@rhythmjs/observability/health";
const healthService = createHealthService({ indicators });
const app = new Rhythm().use(mount(healthRoutes(healthService)));
// GET /health/live -> 200 { status: "up", uptime, timestamp }
// GET /health/ready -> 200 | 503 HealthReportBy default /ready returns only each check's status and durationMs. details: true also returns indicator details and error messages, which can reveal hosts and connection errors, so only enable it behind authentication. service.ready() always returns the full report for in-process use.
Graceful shutdown#
gracefulShutdown(options) ties the pieces to process signals (SIGTERM and SIGINT by default). On the first signal it runs one ordered sequence: flip the healthService to shutting-down (readiness starts failing, so load balancers drain the instance), wait drainMs (default 0), run your close hook (stop the server, app.stop() to run the app's registered cleanups, close databases), then exit 0. The helper owns no resources itself; whatever you created, close releases. A force timer (timeoutMs, default 10 000 ms, unref'd so it never keeps the process alive) exits 1 if the sequence hangs. Repeated signals are ignored once shutdown has started.
import { toFetchHandler } from "@rhythmjs/router/fetch";
import { gracefulShutdown } from "@rhythmjs/observability/health";
const server = Bun.serve({ fetch: toFetchHandler(app) });
const shutdown = gracefulShutdown({
healthService,
close: async () => {
await server.stop();
await app.stop();
},
drainMs: 5000,
});
// the returned function triggers the same sequence manually:
process.on("uncaughtException", () => void shutdown());Set exit: false (and signals: []) to run the sequence without registering signal handlers or exiting the process, useful under test runners, where the returned trigger function replaces the signal.