docs: status pages

2026-08-25 08:44:38 +00:00
parent 57951cabff
commit d69a36ed7b
3 changed files with 129 additions and 0 deletions
@@ -0,0 +1,107 @@
+---
+id: status-pages
+title: Status pages
+sidebar_label: Status pages
+---
+
+A status page is a public page reporting a chosen set of monitors as up-front
+components, with a 90-day history and an uptime percentage per component. It
+needs no session and no token to read — anyone with the link can open it,
+which is the point: it is what you hand a customer instead of an incident
+email.
+
+Requires the **Status pages** licence feature. If the licence lapses, or the
+tier does not include the feature, the page keeps serving — it renders an
+explanation rather than data or a broken page, so a customer who follows an
+old link never sees an error.
+
+## Creating a page
+
+From **Status pages**, choose a page id and a title. The id is 3–40 characters
+of lowercase letters, digits and `-`, starting and ending with a letter or
+digit. It becomes part of the public URL:
+
+```
+https://<your-instance>.vantage.<yourdomain>/status/<page-id>
+```
+
+**The page id cannot be changed after creation.** Once you have shared the
+link, changing the id would break it, so pick something you would still be
+happy with in a year — `platform`, `api`, a customer's own name for a
+dedicated page.
+
+## Draft versus published
+
+A new page starts unpublished. Unpublished pages answer *not found* to
+anyone who requests them, including you, from a browser without a session —
+so you can build out the components and copy before announcing it. Toggle
+**Published** when it is ready. Un-publishing later takes it back to *not
+found* rather than deleting anything.
+
+## Sections and components
+
+A page is organised into **sections** — arbitrary groupings such as "API" or
+"Region: EU" — each holding one or more **components**. A component is a
+monitor plus a **display name** you choose for this page.
+
+The display name is never the monitor's own name unless you type it in. An
+internal monitor name ("prod-db-primary-eu1") is rarely what you want a
+customer reading; give it whatever name makes sense to them, and change it
+for a different page without touching the monitor.
+
+If a monitor listed on a page is later deleted, its component still appears —
+reading `Unknown` rather than up or down, because nothing is checking it any
+more and claiming otherwise would be a false claim of health.
+
+## What a visitor sees
+
+- Component name, current state (up / down / under maintenance / unknown) and
+  a 90-day uptime percentage.
+- A 90-day history bar per component.
+- Any active incidents, upcoming maintenance, and a rolling history of both.
+- An optional banner across the top of the page (info / warning / critical),
+  for anything you want said regardless of component state.
+
+A visitor never sees a target URL, host or port, the check's expected status
+or keyword, latency, a certificate expiry date, failure text, or which
+notification channel is attached. That is a deliberate boundary, not an
+oversight: nothing that would tell a stranger how your infrastructure is
+reachable is on this page.
+
+## Incidents and maintenance
+
+Two kinds of entries appear on a page's timeline:
+
+- **Automatic** — a monitor going down opens an incident on any page that
+  lists it, with no action from you. These appear the moment the monitor's
+  state changes and close the moment it recovers.
+- **Authored** — an incident or maintenance window you create by hand, with
+  its own title, impact and a set of affected components you choose. You
+  post updates to it (Investigating → Identified → Monitoring → Resolved) as
+  the situation develops, and each update is timestamped and kept on the
+  page's history.
+
+An authored incident is attached to one or more pages explicitly when you
+create it — it does not follow a monitor onto every page that monitor happens
+to be listed on.
+
+### Scheduling maintenance
+
+A maintenance window has a scheduled start and end (the end must be after the
+start) and moves through Scheduled → In progress → Completed. While a window
+is in progress and its affected components are within the scheduled time,
+those components are drawn as "under maintenance" instead of up or down.
+
+**Maintenance changes how a day is drawn, never the uptime number itself.**
+The 90-day percentage is computed from what actually happened — a component
+that stayed up throughout a maintenance window still shows as up in its
+history, it is only the live status pill that reads "under maintenance" for
+the duration.
+
+## Delay before an update appears
+
+A visitor's read of a page is cached for up to 30 seconds, so posting an
+update or flipping Published does not necessarily change what a visitor sees
+instantly — though most authoring actions invalidate that cache immediately,
+so in practice it usually shows within a second or two. If a change genuinely
+does not appear, reloading after 30 seconds always will.