Skip to main content

Escalation Chains

The Escalation page (On-Call → Configure → Escalation Chains) is where you build the ordered steps that decide who gets paged, and in what order, once an alert is page-worthy. It uses the Grafana OnCall chain model: a chain is a team-owned escalation policy, customers route into a chain by severity, and the chain's steps page a team's people or schedule.

This page describes the chain workspace. For the paging engine itself (schedules, rotations, the snapshot-at-fire-time model, and the shadow/cutover safety net) see On-call & Escalation Management. For who may see and edit what, see Access & Roles.

The chain workspace at a glance​

The page is a two-pane, Grafana-style layout plus a routes table below it:

  • Chain rail (left) — the list of chains you can see, each row showing the chain name, its owning-team badge, and a 🔗 linked-route count. Selecting a row loads that chain into the builder. A New chain button (managers/admins only) starts a fresh chain.
  • Chain builder (right) — the inline, drag-reorder step editor for the selected chain, plus a Settings affordance and a Linked routes panel underneath it.
  • Routes (below) — the client-scoped routing table. Routing (which alerts enter which chain) is still managed here; the builder never edits routes.
Chains are team-owned; routes are client-scoped

A chain (escalation policy) belongs to a team, not a customer. A route belongs to a client and points that client's alerts (by severity / match) at a chain. That is why the chain rail is auto-scoped to the teams you can see, while the Routes table asks you to pick a project first. This is unchanged from the previous model — the redesign only replaces the modal step editor with an inline builder.

The chain rail​

The rail lists every chain you're allowed to view, already scoped for you server-side — you never see another tenant's chains. Each row carries:

  • Name — the chain's name.
  • Owning-team badge — a neutral badge with the owning team (owner_name), so you can tell two same-named chains on different teams apart at a glance.
  • 🔗 linked-route count — how many routes across all clients currently point at this chain (route_count). A 0 here means no client routes into this chain yet — it would page no one.

Selecting a row opens it in the builder. New chain (shown only if you can manage escalation for at least one team) opens an inline create form: pick the owning team — only teams you may manage are offered — give it a name, and optionally a covering-team role (see below). The new chain is selected in the rail on save.

The inline step builder​

The builder edits one chain's steps as a numbered, top-to-bottom chain — the order is the order they fire. It replaces the old modal dialog: everything is inline, and nothing is written until you press Save policy.

  • Reorder — drag a step by its grip handle to change its position. The list is keyboard-operable: focus a step's handle, press Space to grab it, use the arrow keys to move it, and Space again to drop. Reordering only changes the working order; it is persisted when you Save.
  • Add a step — pick a step type and press Add escalation step. The supported types are Wait, Notify users, Notify users (queue), Notify schedule, and Repeat. Types that are not yet implemented appear greyed out and labelled "roadmap" so you can see what's coming without being able to select it.
  • Edit a step — each step exposes only the parameters that apply to it (e.g. a Wait's duration, a Notify users list, or a Notify schedule picker). A Notify schedule step can only reference a schedule owned by the same team as the chain.
  • Delete a step — remove a step with its trash button; the shortened chain is saved on the next Save.
  • Chain-level fields — the builder header edits the chain name, the repeat count (0–5, how many times the chain loops), and the ack timeout (5–240 minutes, or empty for "ack permanently halts").
  • Delete the whole chain — the Delete button removes the chain. If a route still points at it, the delete is rejected (you'll be told to remove the route first).

Chain settings (covering-team role)​

The Settings affordance on a selected chain owns the covering-team role — the one control the step builder does not edit. When a client picks this chain's team as its covering team, role decides which severities route here automatically:

  • Critical — P1 alerts route to this chain.
  • Default — P2 alerts route to this chain.
  • None — an ordinary, unroled chain (only explicit routes reach it).

P3–P5 are never paged via a covering team. Settings also lets you rename the chain and adjust its ack timeout without opening the full builder.

Linked routes: which clients route into a chain​

Under the builder, the Linked routes panel answers "which clients page through this chain?" — Grafana OnCall's "N linked integrations", mapped to Proxima's client/route model. It lists every route that targets the selected chain, and for each one shows:

  • the client whose alerts flow in,
  • the severity it matches (or "any"),
  • any match labels, a default-route marker, and whether the route is enabled.

The panel is read-only and tenant-scoped: you only see routes on clients you're allowed to view on-call config for (a super-admin sees them all), and it never mutates anything. Clicking a row is a deep link — it jumps down to the Routes table with that client already selected, so you can edit the routing where it actually lives.

Routing is still managed in Routes

The Linked routes panel is a view. To add, reorder, or change a route, use the Routes section below the chains — it's client-scoped and unchanged. The panel just makes the chain → client relationship visible from the chain's side and gives you a one-click path to the route.

What each role sees​

The workspace respects the on-call permission model (full detail in Access & Roles):

  • A responder (no on-call config permission) doesn't reach this page.
  • A team on-call manager sees every chain on a client they can access. Their own teams' chains are fully editable (builder, settings, New chain); every other visible chain renders read-only — steps show as static text, with no drag handle, add/edit/delete, settings, or Save. The read-only affordance is advisory; the backend gate is authoritative, so a mutation on another team's chain is refused (403).
  • A super-admin sees and edits every chain, on every team.