From d69a36ed7b8eca01c2019fe768fc4d5b373d76a0 Mon Sep 17 00:00:00 2001 From: mrhid6 Date: Tue, 25 Aug 2026 08:44:38 +0000 Subject: [PATCH] docs: status pages --- docs/reference/troubleshooting.md | 21 ++++++ docs/vantage/status-pages.md | 107 ++++++++++++++++++++++++++++++ sidebars.ts | 1 + 3 files changed, 129 insertions(+) create mode 100644 docs/vantage/status-pages.md diff --git a/docs/reference/troubleshooting.md b/docs/reference/troubleshooting.md index 93dba82..a539364 100644 --- a/docs/reference/troubleshooting.md +++ b/docs/reference/troubleshooting.md @@ -160,6 +160,27 @@ needs `host`, `port`, `from` and `to`, and Telegram needs both `token` and | Instance degraded despite a valid-looking licence | It expired more than a few days ago. Pasting a new one still works, which is how you recover | | Cannot enrol another server | The server allowance is reached. Raise it in HQ or remove one | +## A status page 404s or shows no data + +**404, and it should be published.** Check the **Published** toggle on the +page's editor — an unpublished page answers *not found* for everyone, +including you, with no session exemption. Also check the host: the public URL +is `.vantage./status/`, the same +per-instance subdomain everything else in Vantage uses. A wrong or missing +subdomain resolves to no instance at all, which is also a 404. + +**Loads, but shows an explanation instead of components.** This is not a +fault — it is the page working as designed. It means either the licence has +lapsed (a self-hosted instance past its grace period, or a cloud instance +between billing events) or the current tier does not include the **Status +pages** feature. Fix the licence or the plan and the same link starts serving +data again with no republish needed. + +**One component reads `Unknown`.** The monitor behind it was deleted while +still listed on the page. Nothing is checking it any more, so the page says so +rather than showing a stale up or down. Remove the component from the page, +or point it at a replacement monitor, in the page's editor. + ## HQ portal problems The portal is a hosted service, so problems with it are ours to fix rather than diff --git a/docs/vantage/status-pages.md b/docs/vantage/status-pages.md new file mode 100644 index 0000000..90f000f --- /dev/null +++ b/docs/vantage/status-pages.md @@ -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://.vantage./status/ +``` + +**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. diff --git a/sidebars.ts b/sidebars.ts index e005805..925e5a9 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -29,6 +29,7 @@ const sidebars: SidebarsConfig = { "vantage/vulnerabilities", "vantage/workloads", "vantage/notification-channels", + "vantage/status-pages", "vantage/secrets", "vantage/browser-console", "vantage/audit-log",