Checks in, incidents out.
Vigil is one FastAPI service with PostgreSQL behind it and Valkey for scan results. It polls on a schedule, writes every answer down, and tells the dashboard.
What a check does
Each site has its own interval, timeout, expected status code, and optional headers. APScheduler runs the checks inside the service, one job per site. A manual check from the panel, or the MCP tool, runs once and stores a result, but it does not open or close incidents.
A check requests the URL. A response with the expected status is parsed as JSON when it can be. If the body has a status of healthy, degraded, or unhealthy, that is the result; any other body, or none, counts as healthy. A different status code is unhealthy, a request that runs out of time is a timeout, and a refused connection is an error.
| healthy | The expected status, with a healthy report or none. Counts as up. |
|---|---|
| degraded | The endpoint's own report says degraded. Counts as up, and opens no incident. |
| unhealthy | A different status code, or a report that says unhealthy. Counts as down. |
| timeout | No answer within the site's timeout. Counts as down. |
| error | The connection failed. Counts as down. |
How an incident opens and closes
First failure
The first down check on a site with no open incident opens one, broadcasts it to open dashboards, and posts to Chirp if a webhook is set.
While it lasts
Each further down check adds to the incident's failed-check count. Nothing else is sent.
First recovery
The first check that is not down resolves the incident, records its duration, and posts the recovery. Three incidents on one site within 30 minutes also post a flapping alert.
An operator can edit an incident's severity and public title, hide it from the public feed, and post updates. Posting a resolved update closes it.
How uptime is kept
The last 24 hours of uptime are counted from the raw checks. A background job summarizes each hour at five past, and each day at 15 past midnight, with the average, 95th and 99th percentile, minimum, and maximum latency and the uptime for the period. Seven, 30, and 90 days are counted from those daily summaries. Raw checks are removed after the retention setting, 30 days by default; the summaries are not.
How a scan crawls a site
A scan is allowed only for websites and front-end apps that have scanning turned on, and runs one at a time per site. The crawler starts at the site's address and follows same-site links breadth-first, five at a time, at the rate you set. It reads robots.txt unless told not to, follows up to five redirects, and gives each page 20 seconds.
Each page is stored with its title, description, text length, a content hash, a footer hash, its links, and what the page checks found. Checks for broken links, titles and descriptions, thin pages, differing footers, and duplicate pages are run on the pages themselves. External links are checked with a HEAD request. The previous scan is kept for 14 days so the Diff tab can compare.
What leaves the service
- Checks and scans request the URLs you gave Vigil, and nothing else.
- With a Chirp webhook set, alerts are posted there. With none set, nothing is sent.
- The fleet diagnostics page and card ask each registered fleet tool for its own diagnostics report, using keys held in the fleet's parameter store.
- If the Chronicle SDK is installed, Vigil's own telemetry goes to Chronicle.
The public status feed is read-only and carries no URLs, headers, or error messages.
Questions about this tool?
Write to Renkara Media Group and a person will answer.