Monitors

A monitor describes one thing to check. Every monitor shares a small set of public fields, and each type adds its own. Names identify a monitor everywhere — in history rows, incidents, badges, metrics and notifications — so they must be unique and are expensive to rename.

monitors: [  {    name: "Website",    description: "Public marketing site.",    group: "Web",    type: "http",    url: "https://acme.com",  },],

Shared fields

http

The common case: request a URL and assert the response.

{  name: "API",  type: "http",  url: "https://api.acme.com/health",  method: "GET",  headers: { authorization: "Bearer ${process.env.HEALTH_TOKEN}" },  expectedStatus: [200, 204],  expectedResponseHeaders: { "content-type": "application/json" },  expectedBodyIncludes: '"ok":true',  expectedBodyExcludes: "maintenance",  expectedJson: { status: "ok", database: { reachable: true } },  timeoutMs: 10_000,  softFail: true,  softFailMs: 1_000,  followRedirects: true,}

A soft retry that succeeds is still recorded as up, with …; recovered on soft retry appended to the message. Latency always measures the whole check, including the retry window, so a soft-failing monitor reports honestly slow numbers.

ssl

Opens a TLS connection and inspects the peer certificate.

{ name: "TLS certificate", type: "ssl", host: "acme.com", port: 443, warnBeforeDays: 21 }

The check fails when the certificate chain is not authorized, when the expiry date cannot be read, or when the remaining lifetime is below warnBeforeDays. Only the last case is flagged expiring, which is what turns the alert into an ssl.expiring event instead of monitor.down.

tcp

Opens a socket and treats a successful connection as healthy.

{ name: "Database", type: "tcp", host: "db.internal", port: 5432, private: true }

Like ssl, this needs a native runtime — node:net — and is unavailable on Cloudflare Workers. Internal hosts are usually paired with private: true so the hostname never reaches the public page.

dns

Resolves a record through Cloudflare DNS-over-HTTPS, so it works in every runtime including Workers.

{ name: "DNS", type: "dns", host: "acme.com", recordType: "A" }

The check fails when the HTTP query fails, when the DNS response status is not 0, or when the answer section is empty.

composite

A composite monitor performs no I/O. It aggregates other monitors from the same check run, which makes it the right tool for "is the product usable", rather than "is this one endpoint reachable".

{  name: "Platform",  description: "Everything needed to sign in and get work done.",  type: "composite",  monitors: ["Website", "Dashboard", "API"],  strategy: "all",}

A composite reports the highest latency among its components, and its message states the ratio, for example 2/3 components healthy (strategy: all). If a component produced no result at all, the composite fails and names it — a misconfiguration must never look like a healthy aggregate.

Grouping and visibility

monitors: [  { name: "Website", group: "Web", type: "http", url: "https://acme.com" },  { name: "Dashboard", group: "Web", type: "http", url: "https://app.acme.com" },  { name: "Queue", type: "tcp", host: "queue.internal", port: 5672, private: true },],

• Monitors with the same group are published as a MonitorGroup whose status is operational, degraded (some failing) or outage (all failing).
• Monitors without a group are rendered on their own, after the groups.
• private: true removes a monitor from the public snapshot entirely, so it never appears in /status, /monitors, badges, Prometheus or the page.

Choosing timeouts and intervals

A check run executes every non-composite monitor concurrently, then derives composites. The slowest monitor therefore bounds the run, not the sum. Keep timeoutMs comfortably below checks.interval so a stalled endpoint cannot overlap the next scheduled run.