Pharos / Docs / v0.5.10

How checks work

Updated 2026-09-08 · Pharos 0.5.10

One command does all of it. The scheduler calls the plain form every minute; --force is the diagnostic tool.

php artisan pharos:check          # only checks that are due
php artisan pharos:check --force  # every enabled check, with output

The three probe types

What turns a component red

A component goes to Major outage once consecutive_failures reaches the check's retry count — two by default. One failure is never enough. The first healthy result flips it straight back to operational.

With the defaults, an HTTP or TCP target is red about two minutes after it starts failing. A heartbeat takes roughly two intervals plus one more run, because silence has to last before it means anything.

What opens and closes an incident

Crossing the retry threshold opens an incident named {component} unreachable, status Investigating, impact major, with one automatic update naming the probe error. A grouping key stops a second incident being opened while one is already open, and it is what powers the repeat-outage counter on the incidents list.

After three consecutive successful checks the incident closes itself and posts a closing update. Incidents you created by hand are never closed by a check.

Heartbeats

POST https://status.example.com/api/v1/heartbeat/hb_xxxxxxxxxxxxxxxxxxxxxxxx

No authentication header — the unguessable path is the credential, so a backup script needs no token. Call it only when the job actually succeeded:

# the status page hears about it only if restic exits 0
30 3 * * * restic backup /data && curl -fsS -m 10 -X POST \
  https://status.example.com/api/v1/heartbeat/hb_xxxxxxxx >/dev/null

Set the component's interval to the ping frequency. A job pinging every five minutes wants an interval of 300, which gives it a ten-minute grace period.