Paging Control
This page describes how Proxima Console decides whether, and whom, to page when an alert fires — covering the full control surface from the coarse per-client on/off switch down to the per-route severity and label matching logic.
How paging works: route-driven
Paging is route-driven. An alert pages a human if and only if an enabled escalation route for that client matches the alert. There is no hardcoded paging gate — no "only P1/P2 pages" rule burned into the engine. The routes and the policies they point at are the single paging control surface.
A route matches on any combination of:
- Severity (P1–P5, per-route) — a route fires for the severities it is authored for.
- Environment — a label/slug selector restricting matching to a specific environment.
- Host — a hostname or IP selector restricting matching to a specific host.
- Label selectors — arbitrary key/value label matchers on the alert.
- Default (catch-all) — a route marked
is_defaultmatches any alert not caught by a more-specific route above it. Position matters: routes are evaluated top to bottom, first match wins.
Because a route carries the severities it covers, you can page on any severity tier you choose — P3, P4, or a mixed set — simply by authoring a route that matches at that tier. Equally, a severity you don't route is never paged.
Safe default: no routes → no pages
A client with no routes never pages anyone. You must author at least one route — or assign a covering team that materializes the default pair of routes — before any paging fires. This is intentional: an unconfigured client is silent, never noisy.
Covering-team shortcut
Assigning a covering team materializes exactly two routes for the client automatically:
| Route | Severity | Target policy |
|---|---|---|
| Critical route | P1 | Team's critical-role policy |
| Default route | P2 | Team's default-role policy |
Covering teams page on P1 (critical policy) and P2 (default policy) only — P3–P5 are not paged via a covering team. There is no severity-null catch-all: if you need to page a covering team at a lower tier, author an explicit route for that severity.
These are source='covering_team' routes and are replaced atomically when you reassign the covering team. Your hand-authored manual routes are never touched by this operation.
Materialization runs on (re)assignment. Covering-team assignments made before this change still carry the old severity-null catch-all — reassign the covering team to re-materialize the bounded P1/P2 pair.
See On-call & Escalation Management — Assigning a covering team for the API and UI details.
Per-client on/off: l1_agent
The l1_agent feature flag is the coarse on/off switch for a client's entire on-call surface. When l1_agent is off:
- No routes are evaluated.
- No escalations are armed.
- No pages fire, regardless of what routes are authored.
Turn it on in the client's Features section (Client Settings, super-admin) to enable paging for that client. The flag does not affect alert ingestion or correlation — alerts still flow in and are enriched — it only gates paging.
Auto-triage vs. manual triage: l1_manual_triage
When the L1 Agent is on, an alert can trigger an automatic AI root-cause analysis (RCA/triage). The triage mode is controlled by the l1_manual_triage feature flag:
| Flag | Mode | Behaviour |
|---|---|---|
absent / false | Automatic | Auto-triage runs when the alert fires (P1 only — see below). |
true | Manual | No auto-triage. An operator triggers investigation on demand. |
Toggle in the client's Features section under "L1 Agent — Investigation mode: Automatic / Manual".
Auto-triage is P1-only
Auto-triage (AI RCA) runs automatically for P1 alerts only. P1 is the only tier where the cost and latency of an LLM investigation is justified without an operator's explicit request.
For P2–P5, the paged engineer triggers triage on demand:
POST /api/v1/alerts/{alertGroupID}/triage
Requires alerts:write. Returns 202 with the alert-group and incident IDs. The on-demand path is identical to the auto path — it reuses the same triage worker and idempotency layer, so submitting it twice for the same alert group does nothing.
When l1_manual_triage is true, auto-triage is disabled for all severities — including P1. The POST /triage endpoint always works regardless of the flag.
Retired: Telegram-group broadcast for alert paging
The v0.1 Telegram-group alert broadcast — which posted alert notifications directly to client group chats — is retired. On-call engineers are now paged exclusively via their personal escalation notification chain (routes → escalation policy → per-user notification chain of telegram / voice steps).
Group posting was removed because it was uncontrolled: any firing alert would broadcast to every bound group, with no per-severity or per-route gating, no ack integration, and no delivery guarantee. The escalation chain model replaces this entirely, giving each on-call engineer a personal, ordered, retried notification sequence with a proper ack fence.
Group posting will return in a later phase as a controlled NOTIFY_CHANNEL escalation step type — an explicit, opt-in step in an escalation policy that broadcasts to a group when the operator deliberately includes it. Until then, group chats receive Jira/Service Desk notifications only, not alert pages.
Summary: the control surface at a glance
| Control | Where | Effect |
|---|---|---|
l1_agent feature flag | Client Settings → Features | On/off for all paging for this client |
| Escalation routes | Admin → Escalation (routes table) | Which alerts page (severity + env/host/labels + order) |
| Escalation policies | Admin → Escalation (policy builder) | Who gets paged and in what order (steps, WAIT, REPEAT) |
| Covering team assignment | Client detail → Covering team | Auto-materializes P1 (critical) + P2 (default) routes into the team's policies; P3–P5 not paged |
l1_manual_triage flag | Client Settings → Features | Auto-triage off (on-demand only via POST /triage) |
| Per-user notification chain | Admin → Users → notification policy | How a paged individual is reached (telegram, voice, WAIT delays) |
Related
- On-call & Escalation Management — schedules, policies, routes, covering teams, cutover.
- Notification Chains — per-user paging channel order and fallback.
- Escalation Dead-Man's Switch — guard against a wedged escalation timer.
- Alerting & Correlation — alert ingestion, lifecycle, and correlation context.