# How uptime checks work

How a check requests its URL from several locations, when a run fails, and when the check goes down, comes back and tells anyone.

An uptime check requests a URL on a schedule, any public `http://` or `https://` address, on
Deutsche Cloud or elsewhere, and records whether it answered as expected and how long the answer took.

## States

| State      | Meaning                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------ |
| `pending`  | Created, resumed or changed, and no run has succeeded or confirmed it down since                             |
| `up`       | Answering as expected. A failed run that is not yet confirmed keeps it `up`                                  |
| `regional` | Up, but the last run failed from fewer locations than the check's `confirmations`                            |
| `down`     | Failed runs in a row reached the check's `failureThreshold`; it stays `down` until two runs in a row succeed |
| `paused`   | Paused: the check sends no requests and notifies nobody                                                      |

## A run

A run asks every location at once (see below). At each location, the request fails when:

- nothing answers within the timeout (10 seconds unless you set 1 to 30), the name does not
  resolve, the connection is refused or reset, the host is unreachable, or the certificate is
  invalid while `verifyTls` is on;
- the final status is outside the expected range, 200–399 unless you set another;
- more than five redirects are followed, or a redirect leads to a URL a check may not request;
- for a keyword check, the text is missing from the first 1 MiB of the body (or present, with
  `not_contains`).

A failed request is retried once after 3 seconds, so one dropped connection does not fail the run.
An address that is not public is not retried. The requests carry the user agent
`EWS-Uptime/1 (+https://console.platform.deutschecloud.app/docs/monitoring/guide/how-uptime-checks-work)`, with your Deutsche Cloud Console's host
name.

## Locations and confirmation

Checks run from the platform's control plane (location `control-plane`) and from each probe
location Deutsche Cloud runs. A run counts as failed when at least `confirmations` locations fail in it
(2 by default, 1 to 3); when fewer fail, the check is `regional` and nobody is notified. With
`alertOnRegional`, one failing location is enough.

The count only includes the locations that answered: a probe that has not reported for two minutes
is not asked, and a run whose locations have not all answered after 75 seconds is decided on what
arrived. A run that no location could judge decides nothing and keeps the state. The control plane
does not judge a URL that resolves to Deutsche Cloud's own console addresses or, for a name under
Deutsche Cloud's domain, to a private address; the probes judge those.

`GET /monitoring/api/locations` (`dcloud monitoring checks locations`) lists the locations: the
control plane first, then each probe location, whether it was heard from in the last two minutes,
and the addresses its requests came from, for a firewall allowlist. The control plane's addresses
are not listed.

## Down and up

- The check goes `down` after `failureThreshold` failed runs in a row (2 by default, 1 to 5). While
  a failure is unconfirmed, the next run comes after at most about a minute instead of the full
  interval.
- A `down` check is `up` (or `regional`) again after two successful runs in a row, confirmed the
  same way.
- A new check's first successful run makes it `up` without telling anyone.

Going down and coming back are each mailed to the check's addresses and posted to its webhook,
once per outage, and told to the subscribers of every status page that shows the check. The outage
log records when the outage started and ended, its cause, the locations that confirmed it and what
was sent.

Pausing a check, or changing what it requests, closes an open outage without telling anyone.

## Limits

- Interval: 1, 2, 5 (the default), 10, 15, 30 or 60 minutes.
- Ports: any except 25, 465 and 587. Methods: `GET` (the default) and `HEAD`; a keyword check uses
  `GET`.
- The checks of every organization together run against one host at most six times a minute (a
  60-second check counts one, a 5-minute check one fifth; each run's requests from several locations
  count as one). Creating a check, resuming it, or changing its host or interval past that is refused
  with `409`.
- Raw results are kept 30 days; the outage log as long as the check exists.

## Related

- [Create an uptime check](create-an-uptime-check.md)
- [Read a check's results](read-check-results.md)
- [Notification webhooks](notification-webhooks.md)
