Health and status page

status gives your app health probes, a check for each dependency, a clean drain on shutdown and SLO burn alerts. Register a check for each thing you depend on, and MainSDK reports the cached state.

status:
  driver: builtin
health:
  live: /healthz
  ready: /readyz
  critical: [db]                       # dependencies that make the app unready
  token: secret:HEALTH_TOKEN           # optional: guards the detailed report
  shutdown:
    deadline: 25s
    drain-delay: 5s
slo:
  availability: 99.9%
  exclude: ["GET /healthz"]            # routes left out of the readings
  alert: { to: [log, telemetry] }
resources:
  critical: ["POST /api/checkout/**"]  # never paused or shed
  shed: { loop: 500ms }
  nice: 10                             # 0 to 19
  retry-after: 5s
  max-pause: 5m

import { status } from "mainsdk";

status.check("payments", async () => (await pingProvider()).ok);

import { it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";

it("is not ready while a critical check is down", async () => {
  const app = createTestApp({ yaml: "schema: 1\nproject: prj_test\nhealth:\n  critical: [payments]\n" });
  app.health.check("payments", async () => false, { critical: true });
  await app.health.start();
  const res = app.health.handle(new Request("http://x/readyz"));
  assert.equal(res?.status, 503);
});

status:
  driver: builtin

Quick start

schema: 1
health:
  critical: [payments]   # not ready while this is down

import { status } from "mainsdk";

status.check("payments", async () => true, { critical: true });

Replace the body with a ping of your provider. The check returns true when the dependency is healthy. It runs in the background, never on a request, so a hung dependency never hangs a probe.

Configuration

health:
  live: /healthz
  ready: /readyz
  critical: [db]               # dependencies whose "down" makes this instance not ready
  every: 10s
  timeout: 2s
  token: secret:HEALTH_TOKEN   # in production, the detail needs this bearer token
  shutdown:
    signals: [SIGTERM, SIGINT]
    deadline: 25s              # from the signal to exit, everything included
    drain-delay: 5s            # report not ready and keep serving; 0 in dev
slo:
  availability: 99.9%          # share of requests that don't fail with a 5xx
  window: 30d
  exclude: [/healthz, /readyz]
resources:
  every: 1s
  hold: 5s                     # a reading must stay over a threshold this long
  pressure: { cpu: 80%, loop: 100ms, memory: 80% }
  shed: { loop: 500ms }        # off unless you add it
  critical: ["POST /api/checkout/**", "job:billing.*"]
  retry-after: 5s
  max-pause: 5m

The values shown for resources are the defaults, except shed and critical.

/healthz answers 200 while the process can respond. /readyz answers 200 with ready or degraded, and 503 with starting, draining or not-ready plus MAIN-HEALTH-0001. It reads cached state. Outside production the body lists every dependency; in production it does so only with the bearer token. On SIGTERM the app reports not ready, keeps serving for drain-delay, then stops taking work, drains requests, jobs, workflow steps and realtime streams, and flushes logs and audit. A resource pressure state never makes /readyz unready, only degraded.

A bad slo value fails mainsdk check with MAIN-HEALTH-0005; a bad critical name or a drain delay too close to the deadline fails with MAIN-HEALTH-0006; a bad resources value fails with MAIN-RESOURCE-0003.

What you get

• /healthz and /readyz from every server adapter, with no route to write.
• Circuit breaker states from the network layer listed as dependencies.
• Request counting for SLOs: a 5xx is bad, a 4xx is good, under 2 microseconds a request.
• Graceful shutdown in a fixed order inside the deadline, and mainsdk status for the current state.

Examples

Check a partner API

import { http, status } from "mainsdk";

status.check("partner-rates", async () => {
  const res = await http.fetch("https://api.partner.com/v1/health");
  return res.ok;
});

Allow the host your check calls with Network permissions. A check that throws, returns false or times out marks its dependency down. A dependency that is not in health.critical shows as down in the detail and /readyz stays 200.

See the state of every dependency

health() lists the cached state of every probe, circuit breaker, the resource watcher and the disk. It never calls a driver.

import { health } from "mainsdk";

export async function GET() {
  const parts = health();
  const down = parts.filter((d) => d.state === "down");
  return Response.json({ ok: down.length === 0, parts }, { status: down.length ? 503 : 200 });
}

Each entry has name, state (ok, degraded or down), since (RFC 3339), critical and sometimes detail. Run npx mainsdk status for the same list in your terminal, one line per dependency with its state. Add --json for machine-readable output. Registered probes appear once the app has started.

Trim caches under pressure

import { resources } from "mainsdk";

const localCache = new Map<string, string>();   // the app's own in-memory cache
const stop = resources.onPressure(() => localCache.clear());

localCache is your own. The hook runs when the instance enters pressure or shed. resources.state() returns ok, pressure or shed, resources.pressure is true while background work waits, and resources.snapshot() returns the state, reasons (cpu, loop, memory), cpu, loop and memory readings and since. onPressure returns a function that removes the hook.

Reference

Calls beyond the examples above. Every parse call reads a section into settings with defaults; every validate call returns the issues that mainsdk check reports.

Errors and checks

Runtime: MAIN-HEALTH-0001 (not ready, 503 on /readyz), 0002 (a request after the app stopped accepting work), 0003 (the deadline cut work), 0004 (a probe threw or timed out), 0010 and 0011 (the availability or latency budget burns too fast). MAIN-RESOURCE-0001 (a request was shed, 503 with Retry-After), 0002 (the state changed), 0004 (nice could not be applied), 0005 (background work waited past max-pause), 0006 (the heap limit is above the container's). Checks: MAIN-HEALTH-0005, MAIN-HEALTH-0006 and MAIN-RESOURCE-0003. See check codes and Error codes.

Swapping drivers

The status driver key (builtin or provider) belongs to the planned status page. Nothing reads it today: probes, drain, SLOs and resources have no driver.

Testing

createTestApp gives you the app with a testing clock, so probes and the SLO run without waiting. Read the probes from the app's health layer.

import { it } from "node:test";
import assert from "node:assert/strict";
import { createTestApp } from "@mainsdk/testing";

it("is not ready while a critical check is down", async () => {
  const app = createTestApp({ yaml: "schema: 1\nproject: prj_test\nhealth:\n  critical: [payments]\n" });
  app.health.check("payments", async () => false, { critical: true });
  await app.health.start();
  const res = app.health.handle(new Request("http://x/readyz"));
  assert.equal(res?.status, 503);
});

The test pattern follows packages/sdk/test/health.test.ts, which also drives shutdown with fake signals and fake workers. The calls above ran against the repository.

Security and privacy

• Health checks and resource watching are free in your app.
• In production the detail needs the health.token bearer token. Keep check results free of personal data anyway.
• MainSDK's own status page, for MainSDK Cloud and TUF delivery, is separate from yours and hosted apart from the Cloud it reports on.

FAQ

Is this the MainSDK status page? No. status is for your app. MainSDK publishes its own page for the Cloud and TUF delivery.

Does my app go down if MainSDK Cloud does? No. No MainSDK service is ever in your request path, and MainSDK Cloud can never be a critical dependency. See Fail static.

Next

• Watch your app's health and resource pressure
• Fail static
• Logs, audit and telemetry
• Network permissions