Raj Nandan Sharma
e27ab6ff7d
Monitor deletion is now available via the v4 API, reusing the same DeleteMonitorCompletelyUsingTag path as the manage UI. While wiring it in, monitor deletion was found to orphan alert configs on SQLite: the code relied on FK cascades that SQLite never enforces (the foreign_keys pragma is off). Delete paths now remove child rows explicitly — v2 alerts, trigger junctions, monitor junctions — in both the by-id and by-tag config deletes; see ADR 0008 for why explicit deletes were chosen over enabling the pragma. Also corrects the CONTEXT.md Stale Member entry (deletion strips group membership and rebalances weights; only pausing produces a stale member), documents the DELETE endpoint in the OpenAPI spec, points the pages doc at the ~home token, and removes an orphaned fictional api-reference markdown page superseded by the spec tab. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
7.4 KiB
Kener
An open-source status page application providing real-time monitoring, uptime tracking, incident management, and customizable dashboards.
Language
Monitoring
Monitor: A single check against a service, with a unique tag, a type (API, Ping, TCP, DNS, SSL, SQL, Heartbeat, GameDig, Group, gRPC, None), and a status (ACTIVE or otherwise). Avoid: Check, probe, service
Inactive Monitor: A monitor that is not checked at all: the scheduler drops its job and no monitoring data is collected until it is made ACTIVE again. Independent of visibility (see Hidden Monitor). Avoid: Disabled monitor, paused monitor
Hidden Monitor: A monitor excluded from all status pages while remaining fully checked and alerted. Independent of ACTIVE/INACTIVE. Avoid: Invisible monitor, private monitor
Group Monitor: A monitor whose status is derived from other monitors via a weighted score (UP=1, DEGRADED=0.5, DOWN=0; maintenance counts as UP). A group cannot contain another group. Avoid: Monitor group, composite monitor
Member: A monitor belonging to a Group Monitor, carrying a weight and a position in the execution order. Membership is an explicit stored list, never a dynamic rule (e.g. tag wildcards). Avoid: Child monitor, sub-monitor
Weight: A member's share of the group score, between 0 and 1. Weights across a group's members must sum to 1. Any membership change (add or remove) redistributes all weights equally; manual tuning happens after membership is settled.
Execution Order: The stored order in which a Group Monitor's members are checked before aggregation. Manually arranged, not derived.
Eligible Monitor: A monitor that may become a Member: ACTIVE, not a Group Monitor, and not the group being edited itself.
Monitoring Sample: One recorded data point for a monitor at a timestamp: a status, a latency, and a sample type describing how it was produced. Every sample is either Observed or Synthetic. Avoid: Data point, record, check result
Observed Sample:
A Monitoring Sample produced by a check that actually ran against the target, whatever the outcome: a clean evaluation (REALTIME), a timed-out check (TIMEOUT), or a check that errored (ERROR). A check failing to reach the target is itself an observation — for most monitor types that is exactly what "down" looks like.
Synthetic Sample:
A Monitoring Sample written by the system or an admin rather than by a check: a raw heartbeat receipt (SIGNAL), a status pushed through the data API (MANUAL), a default-status fill (DEFAULT_STATUS), or an incident/maintenance overlay (INCIDENT, MAINTENANCE).
Stale Member: A Member whose monitor was paused after being added, making it no longer an Eligible Monitor. It remains a Member until explicitly removed, but is excluded from the group score. Deletion never produces a Stale Member: deleting a monitor strips it from every group and rebalances the remaining members' weights equally.
Alerting
Alert Configuration: A per-monitor alerting rule: a condition (status, latency, or uptime against a value), a Failure Threshold, a Success Threshold, whether triggering creates an incident, and the Triggers to notify. Avoid: Alert rule, alarm
Alert: A fired instance of an Alert Configuration for a monitor. TRIGGERED when the condition holds, RESOLVED when the resolve condition later holds. May own the incident it created. Avoid: Alarm, notification (that's what Triggers send)
Trigger: A notification channel (email, webhook, Discord, Slack) that Alert Configurations notify on trigger and on resolve. Avoid: Notifier, channel
Alert-Visible Sample:
A Monitoring Sample that alert evaluation can see: every Observed Sample, plus data-API pushes (MANUAL) and default-status fill (DEFAULT_STATUS). Raw heartbeat receipts (SIGNAL) and incident/maintenance overlays are never alert-visible — while an overlay is active the alert window freezes (alerts neither trigger nor resolve). All alert conditions (status and latency alike) evaluate the same alert-visible timeline.
Failure Threshold: The number of consecutive Alert-Visible Samples matching the condition required to trigger an Alert.
Success Threshold: The number of consecutive Alert-Visible Samples meeting the resolve condition required to resolve an Alert.
Pages
Page:
A public status page with its own path, title, monitors, and display settings. Served at /<page_path>.
Home Page:
The Page served at the site root. Its stored path is empty, it always exists (it can not be deleted), and its path can not be changed. Addressed in the API by the ~home token.
Avoid: Default page, base page, root page
Status History Window: The number of days of per-day status shown for a monitor, per device class (desktop/mobile). Configurable at two levels with the same defaults and bounds: per Page (applies to all its monitors) and per Monitor (overrides the page level). Avoid: History days, bar count
Overall Status: The single status a set of monitors collapses to for display — the page banner, the all-monitors badge. The worst state wins: DOWN > DEGRADED > MAINTENANCE > UP. Maintenance is noteworthy but not a problem: it surfaces only when nothing is actively wrong, and never masks an outage or degradation. Distinct from Group Monitor scoring, which derives a monitor's own status from its members. Avoid: Page status, summary status, aggregate status
All-Monitors Badge:
The badge addressed by the _ token, showing the Overall Status of every ACTIVE, non-hidden monitor site-wide. Not scoped to any Page — on a multi-page install it need not match any single page's banner.
Avoid: Site badge, page badge
Page Settings: A Page's display configuration: status-history window per device class, monitor layout style, per-page meta/social overrides, and event display preferences. The admin UI and the API expose the same settings, though each surface may name fields differently; a writer must never drop fields it does not understand. Avoid: Display settings (ambiguous with site-wide event display settings)
Maintenance
Maintenance: A recurring maintenance definition: title, description, an RRULE schedule, a duration, and affected monitors. Identified by its own id. Avoid: Maintenance window, maintenance event (that's an occurrence, see below)
Maintenance Event: A single occurrence of a Maintenance, generated from its RRULE: a concrete start/end time with a lifecycle status (SCHEDULED → READY → ONGOING → COMPLETED). Has its own id, independent of the Maintenance id. The public maintenance page is keyed by Maintenance Event id. Avoid: Occurrence, maintenance instance
Cancelled Event: A Maintenance Event called off by an admin instead of running to completion. An event not yet started keeps its planned window when cancelled; an ONGOING event that is cancelled — or completed early — has its end time moved to the moment it was ended, so the recorded window always reflects what actually happened, not what was planned. COMPLETED means the work finished; CANCELLED means the occurrence was called off, before or during. Both are terminal: no relabeling, no un-cancel. Avoid: Skipped event, aborted event
Ended Notification:
The subscriber notification sent when a Maintenance Event reaches a terminal status — COMPLETED or CANCELLED, naturally or by an admin. One toggle (ended) governs all of them; there is no separate cancellation toggle.