Observability@rhythmjs/observability
API reference
Exports and signatures for the log, request-id, and timing subpaths of @rhythmjs/observability.
On this page
@rhythmjs/observability/log#
function log(sink?: LogSink): Middleware<RhythmHttpContext>;Returns middleware that measures each request and calls the sink once per request. Without an argument, the default sink prints METHOD /path status Nms to the console. When downstream throws, the sink receives an entry with status: 500 and the error, then the error is rethrown so an outer exception filter still sees it.
LogEntry#- The structured entry passed to the sink:
method: string,path: string(pathname, no query string),status: number,duration: number(rounded milliseconds), anderror?: unknown, set only when downstream threw. LogSink#(entry: LogEntry) => void | Promise<void>. Sync or async; an async sink is awaited before the middleware returns.
@rhythmjs/observability/request-id#
function requestId(header?: string): ExtensionMiddleware<RhythmHttpContext, RequestIdContext>;Returns derive-style middleware that reads the incoming header named by header (default "x-request-id") and reuses its value when it matches ^[A-Za-z0-9._-]{1,128}$, or generates a new id with crypto.randomUUID(). The id is set on the response under the same header name and passed downstream as ctx.requestId.
RequestIdContext#{ requestId: string }. The context extensionrequestId()derives for everything after it; a router that readsctx.requestIddeclares it as its input,new RhythmRouter<RequestIdContext>().
@rhythmjs/observability/timing#
function timing(name?: string): Middleware<RhythmHttpContext>;Returns middleware that appends a Server-Timing header after next() resolves, in the form name;dur=N with the downstream duration in milliseconds to one decimal place, measured with Bun's native Bun.nanoseconds(). The metric name defaults to "app". The header is appended, not replaced, so multiple timing() layers each contribute their own metric. If downstream throws, no header is added.
@rhythmjs/observability/health#
function createHealthService(options?: HealthModuleOptions): HealthService
const healthModule: { forRoot(options?: HealthModuleOptions): Rhythm } // startup context: { healthService }; use with include()
function healthRoutes(service: HealthService, options?: HealthRoutesOptions): RhythmRouter
function gracefulShutdown(options?: GracefulShutdownOptions): () => Promise<void>healthModule.forRoot(options?)#- A Rhythm module (named
"health") whose startup context holds ahealthServicecreated from the same options ascreateHealthService. Pull it into an app withinclude(healthModule.forRoot(options), (health) => ({ healthService: health.healthService })). HealthIndicator#{ name, check(): HealthResult, critical?, timeout? }.criticaldefaults to true; a down critical indicator makes the whole report down; non-critical failures are reported but do not. Each check races its owntimeout(falling back to the module-leveltimeout, default 5000ms) and a throw or timeout counts as down with the error indetails.HealthService#live()returns{ status: "up", uptime, timestamp }, no indicators involved.ready()returns aHealthReport(status,shuttingDown, per-indicatorcheckswith durations), cached forcacheTtl(default 1000ms); concurrent calls share one in-flight run.isShuttingDownandshutdown()flip the service to shutting down, after whichready()reports down immediately.healthRoutes(service, { path?, details? })#- A router (named
"health") with the full-path routesGET ${path}/live(always 200) andGET ${path}/ready(200 up, 503 down);pathdefaults to/health. Add it withmount(...); there is no prefix./readyleaves out indicatordetailsunlessdetails: true. GracefulShutdownOptions#healthService(flipped first),closehook (runs after the drain; stop the server and callapp.stop()here),signals(defaultSIGTERM/SIGINT),drainMs(default 0),timeoutMs(hard cap, default 10 000), andexit(default true; passfalsewithsignals: []in tests). Returns the shutdown function so you can also invoke it directly; it runs at most once.