openstatushq/openstatus

🫖 Status page with uptime monitoring & API monitoring as code 🫖

How Data Flows Through the System

The monitoring pipeline starts when distributed checker applications probe monitored endpoints every few minutes from multiple global regions, measuring response times and status codes. These results flow into the central workflows service which detects status changes and creates incident records when services go down. Status changes trigger notification workflows that send alerts via email, Slack, Discord, and other channels. Public status pages query the incident database to display current service health, while the admin dashboard allows users to configure monitors and view analytics. Screenshots are captured during incidents for documentation purposes.

1. Schedule monitoring checks — The cron service in workflows app sends HTTP requests to checker applications across regions every 30s/1m/5m/10m/30m based on monitor configuration, triggering distributed health checks [Monitor configurations → Check triggers] (config: monitors.periodicity, regions.enabled)
2. Execute endpoint probes — JobRunner in checker apps makes HTTP requests to monitored URLs, measuring response time and status code, handling timeouts and connection errors with configurable retry logic [Check triggers → MonitorResult] (config: monitors.timeout, monitors.retry_count)
3. Aggregate regional results — The checkerRoute handler in workflows service receives MonitorResult payloads from all regions and applies consensus logic to determine overall service status [MonitorResult → Status aggregation] (config: monitors.regions, monitors.degraded_after_failures)
4. Detect status transitions — upsertMonitorStatus compares new status against previous status in database, identifying transitions from operational→degraded→down or recovery patterns [Status aggregation → Status change events] (config: monitors.status_threshold)
5. Create and manage incidents — When failures are detected, findOpenIncident checks for existing incidents and either creates new IncidentRecord or updates resolution timestamp for recovery [Status change events → IncidentRecord]
6. Trigger notifications — triggerNotifications sends alerts to configured channels (Slack, Discord, email, webhooks) when incidents are created or resolved, with customizable message templates [IncidentRecord → Notification messages] (config: notifications.channels, notifications.templates)
7. Display public status — Status page apps query incident and monitor tables to render current service health, historical uptime percentages, and incident timeline for public viewing [IncidentRecord → Status page HTML] (config: status_page.theme, status_page.custom_domain)
8. Capture incident screenshots — Screenshot service receives QStash webhooks when incidents occur, uses Playwright to capture full-page screenshots, and stores them in R2 bucket with incident ID [ScreenshotRequest → Screenshot URLs] (config: screenshot.enabled, storage.r2_bucket)

Data Models

The data structures that flow between stages — the contracts that hold the system together.

Hidden Assumptions

Things this code relies on but never validates. These are the things that cause silent failures when the system changes.

System Behavior

How the system operates at runtime — where data accumulates, what loops, what waits, and what controls what.

Data Pools

Feedback Loops

• Monitor Configuration Refresh (polling, balancing) — Trigger: 10-minute timer in MonitorManager main loop. Action: Fetches latest monitor configs from API and updates scheduled checks. Exit: Context cancellation on shutdown.
• Status Recovery Detection (self-correction, balancing) — Trigger: Successful health checks after previous failures. Action: Resolves open incidents and sends recovery notifications. Exit: When autoResolved flag is set.
• Retry Checker Tasks (retry, balancing) — Trigger: Failed API calls or timeout errors in checker execution. Action: Effect.retry with exponential backoff up to 3 attempts. Exit: Successful execution or max retries exceeded.
• Incident Escalation (recursive, reinforcing) — Trigger: Continued failures after incident creation. Action: Escalates notifications and updates incident severity. Exit: Service recovery or manual acknowledgment.

Delays

• Monitor Check Intervals (scheduled-job, ~30s to 30m based on monitor configuration) — Controls how quickly service outages are detected - shorter intervals provide faster detection but higher resource usage
• Config Refresh Delay (cache-ttl, ~10 minutes) — New monitor configurations take up to 10 minutes to be picked up by checker agents
• Screenshot Processing (async-processing, ~5-30 seconds for Playwright browser launch and page capture) — Incident screenshots appear in reports after brief processing delay
• QStash Delivery (queue-drain, ~Variable based on queue backlog and webhook processing) — Screenshot requests may be delayed during high incident volume

Control Points

• Monitor Periodicity (hyperparameter) — Controls: How frequently monitors are checked (30s/1m/5m/10m/30m). Default: Configurable per monitor
• Regional Coverage (architecture-switch) — Controls: Which global regions participate in monitoring checks. Default: 28 regions across 3 cloud providers
• Notification Channels (feature-flag) — Controls: Which notification methods are enabled (Slack, Discord, email, webhooks). Default: Configurable per workspace
• Screenshot Capture (feature-flag) — Controls: Whether to capture screenshots during incidents. Default: Enabled based on plan tier
• Self-Host Mode (runtime-toggle) — Controls: Authentication providers and feature availability in self-hosted deployments. Default: process.env.SELF_HOST

Technology Stack

Key Components

• MonitorManager (orchestrator) — Coordinates monitor execution by fetching monitor configs from API, scheduling checks with JobRunner, and managing the task scheduler lifecycle apps/checker/cmd/private/main.go
• JobRunner (executor) — Executes individual HTTP checks against monitored endpoints, measures response times and status codes, handles timeouts and network errors apps/checker/pkg/job
• checkerRoute (processor) — Receives monitoring results from checker agents, detects when services transition between operational/down states, creates and resolves incidents apps/workflows/src/checker/index.ts
• upsertMonitorStatus (processor) — Updates monitor status in database and triggers notification workflows when status changes from operational to degraded/down or vice versa apps/workflows/src/checker/alerting.ts
• NextAuth handlers (gateway) — Handles OAuth authentication flows with GitHub and Google providers, manages user sessions, updates user profile data on signin apps/dashboard/src/lib/auth/index.ts
• resolveRoute (resolver) — Parses incoming requests to determine which status page to display based on hostname or pathname routing, resolves locale preferences apps/status-page/src/lib/resolve-route.ts
• screenshot handler (processor) — Receives QStash webhook requests for incident screenshots, launches Playwright browser to capture full-page screenshots, uploads images to R2 storage apps/screenshot-service/src/index.ts
• railway proxy (dispatcher) — Routes incoming checker requests to appropriate regional checker instances based on Railway region headers apps/railway-proxy/main.go
• Hono app server (gateway) — Main API server that mounts RPC routes, handles public status endpoints, manages request logging with OpenTelemetry, serves OpenAPI documentation apps/server/src/index.ts

Package Structure

Related Fullstack Repositories

Frequently Asked Questions

Analyzed on April 20, 2026 by CodeSea. Written by Karolina Sarna.