Checks

Checks are the detection layer of the reliability product. A check is a monitor attached to a catalog project: it probes a target on a schedule, keeps an up or down state, and on a confirmed failure it can post to an alert channel or declare an incident and page on-call. Detection, routing, and response in one place, on the services you already describe.

Check types

HTTP: request a URL and assert on the status code and response time.
Keyword: an HTTP check that also requires a string to be present (or absent) in the body.
TLS expiry: warn or fail when a certificate is within N days of expiring.
TCP: confirm a port accepts connections (databases, brokers, non-HTTP services).
Heartbeat: the inverse. A job pings a URL Flagon gives you, and the check fails if the ping is late. Ideal for cron jobs and batch work (see below).

Creating a check

On a project, open Checks, then Add check (owner or admin). Give it a name, a type, its target, and an interval. Under On a confirmed failure, choose what happens.

Confirmation, not noise

A single bad probe never alerts. Every check has two thresholds:

Failure threshold (default 3): how many probes must fail in a row before the check is down and its action fires.
Recovery threshold (default 2): how many must pass in a row before it is up again.

Between those, the check sits in a degraded state that is recorded but does not page. This hysteresis is what stops a flaky endpoint from paging you every minute.

What happens on failure

A confirmed failure can do any combination of:

Notify channels: post to one or more alert channels (Slack, webhook, or email).
Email the owning team: a zero-config fallback that emails the project's owning team directly, so a check is useful before you set up any channels.
Open an incident: declare an incident at a chosen severity, attach this service, and hand off to your escalation policy. The incident auto-resolves when the check recovers. A flapping check never opens a pile of incidents: it holds one open incident at a time.

Escalate over time

Prefer a soft nudge first? Notify a channel on failure, and if the check is still down after N minutes, escalate to an incident. Detection thresholds decide whether something is real; your escalation policy decides who gets woken up and when. The two stay separate so you never get double-paged.

Heartbeat checks

A heartbeat check has no outbound target. Instead, Flagon gives it a secret ping URL. Have your job hit it on schedule, and the check fails if a ping is late (the interval plus a grace period). Add it to the end of a cron job:

Shell

# At the end of your nightly job
curl -fsS https://api.flagon.io/ingest/heartbeat/{org}/{token}

The URL is shown on the check's detail page after you create it. Treat the token as a secret.

Over the API

Checks are project-scoped. Everything the console does is available on the API.

Shell

# Create an HTTP check that opens a SEV2 incident on failure
curl -X POST https://api.flagon.io/v1/orgs/{org}/projects/{project}/checks \
  -H "Authorization: Bearer $FLAGON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "homepage",
    "name": "Homepage",
    "type": "http",
    "target": { "url": "https://yourapp.com/" },
    "intervalSeconds": 300,
    "action": {
      "mode": "incident",
      "channelKeys": ["ops-slack"],
      "incident": { "severity": "sev2", "autoResolve": true }
    }
  }'

# Run it now and read the result
curl -X POST https://api.flagon.io/v1/orgs/{org}/projects/{project}/checks/homepage/run \
  -H "Authorization: Bearer $FLAGON_TOKEN"

# Recent heartbeat history
curl https://api.flagon.io/v1/orgs/{org}/projects/{project}/checks/homepage/results \
  -H "Authorization: Bearer $FLAGON_TOKEN"

See the full schema in the API reference.