---
title: Root cause analysis
description: What an incident page tells you — expected vs. detected, which locations confirmed it, why it usually happens, diagnostics to run and the rule version.
canonical: https://watchfor.io/docs/alerting/root-cause
---

# Root cause analysis

What an incident page tells you — expected vs. detected, which locations confirmed it, why it usually happens, diagnostics to run and the rule version.

When an incident fires you should not have to guess what went wrong. Every
incident page opens with a **Root Cause Analysis** panel built from the checks
that confirmed the failure, the rule that fired and a knowledge base of what
each failure usually means. It renders instantly and reads the same for every
incident — no AI in the loop.

**Also via API:** [`GET /v1/incidents/{id}`](/docs/api/incidents#get-an-incident)
returns the same message, rule snapshot and confirming locations for scripts
and AI agents.

## What you see

- **What happened** — a plain-language line for non-engineers: what visitors
  experienced ("users saw an error page") and whose side the problem sits
  on (your server, DNS, a certificate authority, the network in between).
- **Confirmed from** — the locations that saw the failure, and, if any,
  the locations that **still see the site fine**. A *partial* failure points
  at a regional or routing issue rather than a global outage; only
  multi-location checking can tell you that.
- **Diagnosis** — the failing condition as a title (*Connectivity Failure*,
  *Unexpected HTTP Status*, *High Response Time (Latency)*, *Condition
  Violated*…) with its severity.
- **Expected vs. Detected** — what the rule required ("HTTP status in
  2xx/3xx", "response time within 2000 ms", "certificate valid for more than
  14 days") next to what was actually measured ("503", "4.2 s", "9 days").
- **Why this happens** — a short explanation of what the detected status,
  error or metric usually means and the most likely causes, ordered by how
  often they turn out to be the answer in practice.
- **Quick diagnostics** — copy-paste terminal commands with your real host
  substituted (`dig`, `curl -I`, `openssl s_client`, `mtr`…) and links to the
  matching [free tools](/docs/tools) so you can verify from a browser in one
  click.

Below the panel, the incident page adds a **response-time chart** with the
monitor's warning and critical thresholds drawn in, and the **confirming
probes**: each check that confirmed the failure, per location, with its
timestamp, duration, status code or error, and — where the type provides it —
response headers, a body snippet or the raw output. Ping incidents show
round-trip time and packet loss instead of a misleading "duration".

## Why the rule version matters

Alert rules are versioned. When an incident fires, WatchFor records the exact
rule version in effect, and the analysis always shows **that** version as
"Expected". If the rule is changed while the incident is open, the panel adds
an **Updated** entry for each later version with the change highlighted — you
can see that a threshold was raised at 10:42, and that the incident was
judged against the old one. Changes made after the incident resolved are not
shown here; they belong to the monitor's rule history.

## Type-aware details

The analysis is tailored to the monitor type. Some examples:

| Type | Detected value shown |
| --- | --- |
| **HTTP / API** | Status code (with the expected classes), response time against the threshold, body-match failure, failed assertions |
| **Ping** | Round-trip time and packet loss |
| **SSL / TLS** | Which validity check failed — expiry with days remaining, hostname mismatch, untrusted chain, TLS version |
| **DNS** | Expected vs. actual records, lookup time, error count |
| **Heartbeat** | The missed schedule (expected ping interval and grace), failed run or exit code |
| **MCP** | The MCP metric that fired — tool count, inventory drift, handshake time or protocol version — with the observed value |
| **Domain** | Days until expiry from the registry |

> **Info**
>
> Latencies and durations are shown in real units (ms / s), and the
> response-time chart offers a logarithmic scale so a single huge spike does
> not flatten everything else.

## Related

	- [How incidents work](/docs/alerting/incidents): Lifecycle, acknowledging, faster checks while open.
	- [HTTP status codes](/docs/reference/http-status-codes): What each status code means when a monitor sees it.

---

Canonical page: https://watchfor.io/docs/alerting/root-cause · All docs: https://watchfor.io/docs · Site guide: https://watchfor.io/llms.txt