Diagnostics Beta
"It's down" is the easy part. When a monitor fails, we run the same target again in stages and record what each one did, so the outage arrives with a likely cause attached.
Every endpoint here needs an X-API-Key header whose owner has access to uptime monitoring, and each call counts once against your daily quota. They are all read-only. See Monitoring API: getting started for authentication, rate limits and errors.
Endpoints
| Method | Endpoint | Does |
|---|---|---|
GET | /api/v1/monitors/{id}/analysis | Recent diagnoses for a monitor |
GET | /api/v1/monitors/{id}/analysis/{aid} | One diagnosis, with every stage and any traceroute |
GET | /api/v1/traceroute | A traceroute to a host, on demand |
The stages
Each diagnosis runs the target again, one stage at a time, in this order. Every stage is { stage, ok, ms, detail, error }.
| Stage | What it does | What detail holds |
|---|---|---|
dns | Looks the name up. | The addresses it points at. The step also carries addresses with the family of each. |
tcp | Connects to the port. | What it connected to. Skipped when there is no port to try. |
tls | Checks the certificate. | The protocol, the issuer and the days left. A certificate that isn't trusted, or that has expired, fails here. Web checks over HTTPS and mail checks using tls. |
http | Makes the request. | The status, the server header and where it redirects. The step also carries an excerpt: the first 400 characters of the reply. Web types only. |
protocol | Runs the type's own engine. | What a TCP, UDP, ping, DNS or mail check made of the target. Non-web types only. |
Reading the result
- The first stage that fails is the cause, and the stages after it are skipped: they would only fail for the same reason.
causeisdns,tcp,tls,http,protocolornone.nonemeans everything answered when the diagnosis ran, so the problem may have passed. Thesummarysays so.summaryis the one-line version, up to 300 characters. It's the failing stage's error, or the "everything answered" line.- A traceroute is attached when a connection failed (the
tcporprotocolstage) and the checking server can run one. Otherwise it'snull.
When a diagnosis runs
- The worker runs one when a monitor goes down, using the same target the check used.
- At most one diagnosis per monitor every 10 minutes, so a long outage doesn't fill the history.
- They're kept for 90 days.
- The monitor page in the app shows the five most recent.
- A diagnosis never changes a monitor's status: it explains an outage, it doesn't decide one.
Related
- Analysis list: the diagnoses for a monitor
- Outages: the outages they explain
- Results: the individual failed checks