A database migration at 02:00 on Sunday takes the API down for eight minutes. You planned it, you tested it, you told the team. Then the on-call phone rings at 02:01, an incident opens on the status page, subscribers get an email saying the API is down, and the person doing the migration spends the next ten minutes explaining that everything is fine instead of watching the migration.
That is the cost of a monitor with no concept of planned work. It is also, in the other direction, the cost of switching monitoring off: the migration runs long, the API is still down at 02:40, and nothing notices because you muted it.
A maintenance window is the tool that sits between those two failures. Used well, it silences exactly what should be silent and hides nothing that should be visible. This post is about where that line is.
What a maintenance window should silence
Alerts to operators. During a window you have declared, a check that fails inside it should not page anyone, should not open an incident on the status page, and should not email subscribers that something is wrong. The people who would receive those signals already know, because you told them. An alert during planned work is a false alarm by definition, and false alarms are what teach a team to sleep through the real one.
That is the whole list. Everything else stays on.
What it must never hide
The measurement. Probes keep running through the window. The raw history keeps recording what they saw. If the API was down for eight minutes, the history says eight minutes. A window changes who gets told, not what happened. A monitor that stops probing during maintenance cannot tell you when the maintenance ran long, which is the single most useful thing it could tell you at 02:40.
The window itself. A status page in maintenance should say so, prominently, with the time range. Visitors arriving during the window should see "scheduled maintenance, 02:00 to 02:30 UTC, the API will be unavailable," not a green board with nothing wrong. The green board would be a lie, and the visitor who just got an error from your API knows it.
Components outside the window. If the window covers the API, the website is not in maintenance. A failure on the website during that half hour is a real incident and gets the full treatment: page, incident, email. Scoping matters; a page-wide window used for an API migration is a blanket over everything.
Recovery. When the window ends, normal rules resume immediately. A check still failing at the end of the window is an outage, and the alerts that were held during the window should fire now. Overrun is the failure mode planned work has, and the monitor should be the thing that catches it.
Scope it to components, not to the page
The design decision that matters most. Early status page tools treated a maintenance window as a property of the whole page: everything went yellow, all alerting paused. That is simple and usually wrong, because maintenance is almost never on everything.
On RealUptime a maintenance window is scoped to the components it names. Components inside an active window are excluded from incident detection: down is expected there, you have already published the window, and a warning during planned work would be the kind of false alarm that teaches people to ignore the real one. Components outside the window keep every rule. A window that names no components is page-wide, which exists for the genuine case of taking everything down, and should be the exception.
Operator channels are what a window silences: Slack, operator email, PagerDuty, webhooks. It is the same set that a region quorum setting silences, and for the same reason. The public record on the status page stays true either way.
Tell subscribers before, not during
A window you schedule in advance is only useful if the people it affects hear about it in advance. Someone who finds out about maintenance by getting an error and then visiting the status page has learned nothing from the scheduling.
So subscriber notifications for maintenance work like this on RealUptime:
- Creating a window announces it. A window created with its end in the future sends subscribers a "maintenance scheduled" notice with the components and the times. A window created entirely in the past, a record-keeping entry, sends nothing; there is no future event to warn about.
- Starting notifies once. When the start time arrives, subscribers get "maintenance starting." A window created while already underway sends this immediately, because "starting now" is the most urgent case, not the least.
- Rescheduling re-announces only when it matters. Moving the start or end time, or changing which components are covered, sends a fresh notice. Fixing a typo in the title mails nobody, because a subscriber who gets a new email for a comma stops reading them.
- Cancelling apologises only when it owes one. Deleting a window that was already announced sends a short "maintenance cancelled" note. Deleting one nobody was told about is silent.
These go through the same delivery path as incident email, with the same unsubscribe handling, so a subscriber's choices apply consistently. The notices are part of the window, not a separate thing to remember to send.
A checklist for the next one
- Create the window before the work, scoped to the components the work touches. If you are not sure which components, that is a sign the components are too coarse.
- Put the honest time range on it, with a margin. If the migration should take ten minutes, a 30-minute window is fine. A three-hour window "to be safe" hides a two-hour overrun.
- Do not touch the monitors. No pausing, no disabling. Let them measure.
- Watch the monitors during the work. The per-region view will show you the moment the API comes back, and the moment it does not.
- End the window when the work ends, not when the window was scheduled to end. If you finished early, the next fifteen minutes of alerting is real again.
- If it overruns, let the alerts fire. That is not a failure of the window. That is the window working.
The principle underneath
Every rule here is one rule: a maintenance window changes who is told, never what is measured or what the public sees. The moment a window is allowed to hide a measurement or paint a board green, it stops being a maintenance window and becomes a way to make the monitor agree with you.
Windows are included on every RealUptime status page, free tier included. Scope one to the component you are about to work on, and let the monitor keep watching.