Browse the docs

Rules and automatic incidents

Link a monitor to a component and decide what a failure does: status, draft or published incident.

On this page
  1. Add a rule
  2. What happens on failure
  3. What happens on recovery
  4. Manual changes and incidents still win
  5. API

A monitor on its own only knows up and down. Rules connect it to the page: which component it speaks for, what status to set, and whether to open an incident. They are the part that lets the page stay right at 3 am.

Add a rule

Open the monitor and find Rules. Each rule has three settings:

Componentselectrequired
The component this monitor represents. Any component on any page in the workspace.
On failure, set status toselect
The status the component takes when the monitor goes down. Default is Outage; use Degraded for something that slows rather than breaks.
Incidentselect
None: only the status changes. Draft (default): an incident is created but not published, for you to review. Publish: the incident is published immediately and subscribers are notified.

A rule can name a message template for the incident's words. Without one a short default is used.

A monitor can have several rules, for example to drive a component on the public page and another on an internal page. Saving replaces the whole set.

What happens on failure

  1. The monitor reaches its failure threshold and is marked down. A monitor.down event goes to outbound webhooks.
  2. For each rule, the component's status is set as configured. The page snapshot rebuilds within seconds.
  3. If the rule says draft, an incident appears under Drafts with the affected component and the template's wording. If it says publish, it goes live and subscribers hear about it.

What happens on recovery

  1. The monitor reaches its recovery threshold and is marked up. monitor.up goes to webhooks.
  2. Each component is set back to Operational, but only if it still has the status the rule set. If someone changed it by hand in the meantime, the manual status wins.
  3. Open incidents that this monitor created get an automated update and are resolved.
Draft is the default for a reason. It gives you the component change immediately, which is what customers need, and a prepared incident you can read before it goes out with your name on it. Switch to Publish for components where a silent status change is not enough.

Manual changes and incidents still win

Rules never fight a person. A manual status override, or an incident that sets a component override, takes precedence until it is cleared. Rules only restore Operational when the component is exactly as they left it.

API

PUT /user/monitors/:id/rules replaces the rule set with [{ component_id, set_component_status, auto_incident, incident_template_id }]. See Monitors in the API reference.