Monitors

Start with an HTTP monitor for a public endpoint. Add other types when you need to watch a certificate, a port, DNS or the health of several services together. Each monitor has a unique name; changing it later breaks the link to its existing history, incidents and metrics.

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

Fields every monitor shares

The fields below also apply to SSL, TCP, DNS and composite monitors.

http

An HTTP monitor requests a URL and checks its response. Use response assertions when a 200 alone isn't enough to tell whether the service works.

{  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

Use an SSL monitor to check a host's TLS certificate and warn before it expires.

{ 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

Use a TCP monitor when opening a connection is enough to confirm a service is reachable.

{ 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

DNS monitors resolve a record through Cloudflare DNS-over-HTTPS. They also work on Workers, where TCP and SSL checks aren't available.

{ 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

To show whether the product as a whole is usable, combine existing monitors. A composite makes no network request: it uses the results from the same check run.

{  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.