Concepts Maintenances

Maintenances

A Maintenance window declares planned, expected downtime for one or more Services. It exists so that scheduled work doesn't get misreported as an outage — alerts are suppressed and uptime history stays accurate during the window, while users still see a clear notice on the status page.

Key properties

Field	Type	Description
Title	string	Required, shown on the status page
Description	string?	Optional detail about the planned work
StartDateTime	long (unix seconds)	Start of the first occurrence
RRule	string	iCalendar RRULE string defining recurrence (e.g. FREQ=WEEKLY;BYDAY=MO)
DurationSeconds	int	How long each occurrence lasts
Status	MaintenanceStatus	Active or Cancelled — the maintenance definition's lifecycle
IsGlobal	bool	When true, affects all services regardless of explicit associations

Source: Maintenance.cs

Recurrence via RRULE

A single Maintenance defines a recurrence pattern once — you don't create a separate record for every Tuesday-night deploy window. The RRule field uses standard iCalendar RRULE syntax, the same format used by calendar apps:

FREQ=WEEKLY;BYDAY=MO          # every Monday
FREQ=DAILY;INTERVAL=1         # every day
FREQ=MONTHLY;BYMONTHDAY=1     # first of every month

A background job (MaintenanceSchedulerJob) materializes each upcoming occurrence as a MaintenanceEvent — a concrete start/end pair with its own status:

Scheduled → Ongoing → Completed (or Cancelled)

Source: MaintenanceEvent.cs, MaintenanceEventStatus.cs

Display status

The status shown to users is a derived combination of the maintenance definition's Status and its events' temporal state:

Display status	Meaning
Scheduled	No event is ongoing right now, but one is upcoming
Active	At least one event is currently ongoing
Completed	All events have finished and none remain scheduled
Cancelled	The maintenance definition itself was cancelled

Source: MaintenanceDisplayStatus.cs

How maintenance suppresses alerts

While a MaintenanceEvent is Ongoing for a given service (either directly associated or via IsGlobal):

• Checks still run against the service as normal.
• Failing results do not fire alerts — no false-positive pages during expected downtime.
• Results are recorded with a synthetic MAINTENANCE status point in the time series, rather than DOWN, so historical uptime calculations aren't skewed by planned work.

Affected services

A maintenance can target specific services via MaintenanceService associations, or set IsGlobal = true to cover every service without listing them individually.

Where to configure

Admin panel → Maintenances

Create a maintenance window, define its recurrence and duration, choose affected services (or mark it global), and cancel it if plans change.

Tips

• Prefer a single recurring maintenance over creating one-off windows manually every week — RRULE keeps it low-maintenance (pun intended).
• Set the duration generously enough to cover typical overruns; a maintenance ending early is harmless, but checks failing just after it ends will fire real alerts.
• Use IsGlobal sparingly — it's meant for full-platform downtime (e.g. a database migration), not routine per-service work.

Related

• Services — the services a maintenance window can target
• Checks — checks that keep running (but won't alert) during a maintenance window
• Incidents — for unplanned disruptions, as opposed to planned maintenance