Routing & Escalation

Routing decides which response path owns an alert. Escalation decides who is tried and how long Moneat waits before moving to the next step.

Escalation policies

Open Settings → Alerting → Escalation to create an ordered policy. Each step specifies who to notify and how long to wait before escalating. A typical policy might:

1. Notify the primary on-call through push notification and Slack.
2. Notify the secondary on-call after five minutes without acknowledgement.
3. Notify the engineering manager after another ten minutes.

When the last step and every repeat pass without an acknowledgement, the escalation is exhausted: nobody else will be paged, and the alert stays triggered so it still needs an owner. The alert shows Exhausted in the dashboard and in Slack, and its timeline records when it ran out. An escalation that stops because its policy can't go on, such as a step that no longer exists, shows Failed instead. Acknowledge the alert to take it, or resolve it once the problem is handled.

Preview a policy

The policy editor previews the steps you're editing before you save them. Choose the alert's priority, when it starts, and when it's acknowledged, measured from the first page. For each step the preview shows who it notifies at that moment, when the page can go out, when acknowledgement is due, including deadlines set by a working-hours calendar, and the urgency. For a step with a condition it shows which way the alert goes and what the condition read. It uses the rules escalation runs on and pages nobody. A round-robin step lists every target it rotates through, since the one it pages depends on earlier alerts.

A preview is out of date once you change the steps or the preview's inputs, or when a schedule or calendar it read, or who it reaches, changes. Through the API, POST /v1/escalation-policies/preview takes the policy's steps or path, or a policyId alone for its published version, and returns a fingerprint. Send the same startsAt with that fingerprint as expectedFingerprint to recheck it; the response is 409 when the preview no longer holds.

Priority levels

Business hours

Business hours are working-hours calendars, kept under Settings → Working hours. Each calendar has a time zone, weekly hours, and exceptions such as holidays. Two places read them:

• An alert route can page only during a calendar's hours. Outside them, a matched alert is still grouped and can still open an incident, but its page is held. When the calendar opens, Moneat sends the held page if the alert is still firing and nobody has suppressed it. A route that pages the first episode in each group still pages that group once.
• An escalation policy can branch on a calendar or wait for it to open or close, so it can use different steps and timeouts during and outside working hours.

To stop error alerts from paging at night, give the route that names them a calendar under Paging → When to page; an error still firing when the calendar opens pages then. A calendar in use by a route or policy cannot be deleted.

An alert's own page goes to the escalation policy of its resource's owner, or of its source. That page goes out at any time for P0–P2. For P3 and below it goes out only inside the organization's business hours; outside them it is held and sent when business hours begin, if the alert is still firing.

Alert Routes

Automatic incident creation is configured separately through ordered Alert Routes:

• An enabled route must explicitly turn on Create an incident for matched alerts. A route that only pages or groups alerts will not create an incident.
• If no route matches, the alert remains an alert episode: it is not paged by a route and no incident is opened.
• Routes are evaluated in order. A first matching page-only route prevents later routes from handling the alert, so put incident-capable routes before catch-all paging routes.
• The route editor and test-alert result identify whether no route matched, paging occurred, grouping occurred, an incident was skipped, or a triage incident was created.
• The administrator test-alert response is action-specific: a successful alert request does not imply an incident. Review the route state, matched route revision, group, paging result, and incident result separately.
• The editor includes an opt-in P0–P2 triage preset. It pages once per group, creates triage incidents, and derives SEV-0, SEV-1, or SEV-2 from P0, P1, or P2; fixed-severity route settings are unchanged.
• An on-call alert detail shows the matched route revision and independent grouping, paging, and incident outcomes with the reason when an action is skipped or fails.
• Manual Declare Incident remains available independently of Alert Route automation.

Route configuration

Alert Routes are evaluated from top to bottom. The first enabled route whose conditions match owns the alert; later routes are not evaluated. Conditions are OR across groups and AND within a group. Put incident-capable routes above broad paging-only or catch-all routes, and use the editor's preview and test result to see which route revision would win.

Each route independently controls:

• Paging — no page, the first episode in each group, or every episode. Targets can be users, teams, on-call schedules, or escalation policies. When to page limits paging to a working-hours calendar; outside its hours the route holds the page until the calendar opens.
• Grouping — choose up to eight alert attributes as grouping keys, a fixed window anchored on the first alert, or a rolling window extended by each new alert.
• Grouping behavior — Suggested records a candidate relationship for a responder to confirm; Automatic attaches matching episodes and can create the configured incident without a manual confirmation.
• Incident creation — leave it off for an alert-only group, or enable it and choose Triage or Active. Active creation requires a fixed incident severity. A triage incident with no fixed severity, or one set to follow the alert's priority, starts at the severity that priority maps to: P0 is SEV-1, P1 is SEV-2, P2 is SEV-3, and P3 to P5 are SEV-4. Accepting it keeps that severity unless the responder changes it.
• Recovery — choose a grace period, whether to cancel outstanding escalations, and whether an unaccepted triage incident should be declined when every member episode resolves.

An alert-only group can still page and group episodes without opening an incident. To convert an on-call alert manually, open the alert and choose Declare Incident; the new incident is linked to that alert. To convert a grouped alert episode, confirm or attach the suggested incident from the group controls, or use an automatic route with incident creation enabled.

Silences and recovery

When alert delivery is silenced, Moneat records the matched route and group but holds paging and incident actions. When the silence ends, an alert that is still firing and has notified nobody yet is delivered then, page and incident included. When all active episodes in a group resolve, the recovery worker waits for the configured grace period, cancels escalations when selected, and can decline an unaccepted triage incident. Recovery decisions remain visible in the group and incident timelines.

Test the winning route

Creating an Alert Route does not itself exercise it. Send a test alert that satisfies the route's conditions, then inspect the matched route revision, group, paging, and incident outcomes. If there are no Alert Routes, alerts remain alert episodes and no automatic incident is opened; manual declaration still works.

For outcome-specific checks, see Troubleshooting.