Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/openstatusHQ/openstatus. 🫖 Status page with uptime monitoring & API monitoring as code 🫖 openstatus.dev
bun drizzle-orm monitoring monitoring-as-code nextjs observability on-call open-source shadcn-ui status-page statuspage synthetic-monitoring tinybird turso uptime uptime-checker uptime-monitor
Something went wrong. Try again.
MDX
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320---category: Referencetitle: Page Components Referencedescription: Complete specification for openstatus page components on status pages.---
Page components are the individual elements displayed on your status page that show the operational status of your services. They provide a flexible way to organise and present both monitored services and static content on your status page.
**Key features:**
- Support for both monitor-linked and static components.- Organise components into logical groups.- Custom ordering and arrangement.- Individual status tracking with incidents, reports, and maintenances.- Granular control over what appears on your status page.
## Component types
Page components come in two distinct types, each serving different purposes on your status page.
### Monitor components
**Type:** `monitor`
Monitor components are linked to an active monitor in your workspace. They automatically inherit the monitor's status and display real-time health information.
**Characteristics:**- Display live monitor status (up, degraded, down).- Show active incidents from the linked monitor.- Include historical uptime data.- Reflect the monitor's current operational state.- Automatically update when the monitor changes.
**Use cases:**- Displaying API endpoint health.- Showing website availability.- Tracking critical service dependencies.- Monitoring infrastructure components.
#### Configuring monitor components
When you create a monitor component, you link it to an existing monitor in your workspace. This connection provides several benefits:
**Automatic incident tracking:**When your monitor detects a failure (connection timeout, HTTP error, assertion failure), an incident is automatically created and displayed on the status page. The component will show an **error** status until the monitor recovers.
**Real-time status updates:**The component reflects the current operational state of your monitor. If the monitor is actively checking and healthy, your visitors see a **success** status. If checks fail, they immediately see the issue.
**Historical data visualization:**Monitor components display historical uptime data through status trackers. Depending on your [tracker configuration](/docs/guides/how-to-configure-status-page#1-components-configuration), you can show:- **Absolute bar with duration card**: Shows the time spent in each status (success, error, degraded, maintenance).- **Absolute bar with request card**: Shows the number of successful vs. failed requests.- **Manual bar**: Shows only the most significant status of each day.
**Uptime calculations:**Monitor components calculate uptime percentages based on:- Duration of successful vs. failed checks (for duration-based tracking).- Number of successful vs. failed requests (for request-based tracking).- Includes incidents and status reports in the calculation.
**Monitor selection:**When adding a monitor component, the dashboard shows you available monitors with indicators for:- **Public/Private status**: Whether the monitor is already public.- **Active status**: Only active monitors can be linked.- **Already linked**: Monitors already used on this status page are unavailable.
<Aside type="tip">You can customize the component name to be different from the monitor name. For example, your monitor might be named "prod-api-health-check" internally, but the component can display as "API Server" for your visitors.</Aside>
**Status hierarchy:**
1. **Error** — active incidents from the linked monitor, or a status report with a `major_outage` [impact](/docs/reference/status-report#component-impacts).2. **Degraded** — unresolved status reports affecting this component.3. **Info** — ongoing scheduled maintenance.4. **Success** — healthy and operational.
**What affects monitor components:**
- Automatic incidents (from monitor failures).- Manual status reports.- Scheduled maintenances.
### Static components
**Type:** `static`
Static components are independent elements not linked to any monitor. They allow you to display services or systems that you manually manage through status reports and maintenance windows only.
**Characteristics:**- No automatic status updates.- Status controlled exclusively by manual status reports and scheduled maintenances.- Useful for third-party services or manual tracking.- Do not display incidents (no automatic incident creation).- Provide flexibility for non-monitored services.
**Use cases:**- Third-party service dependencies (e.g., payment providers like Stripe, email services like SendGrid).- Manual status tracking for systems without monitors.- Services monitored through external tools.- Components that only need maintenance window communication.- Legacy systems without API endpoints to monitor.
<Aside type="caution">Static components **only** respond to manual status reports and scheduled maintenances. They never automatically detect issues or create incidents. If you need automatic failure detection, use a monitor component instead.</Aside>
#### Managing static components
Static components give you full manual control over what your visitors see:
**Status reports:**Create status reports to indicate issues or degraded performance for static components. For example:- "Stripe payment processing experiencing delays" (degraded performance impact).- "Email delivery service partially unavailable" (partial outage impact).
Once you resolve the issue and mark the status report as resolved, the component returns to a success status.
**Maintenance windows:**Schedule maintenance windows to inform visitors about planned downtime:- "Scheduled database backup - Sunday 2:00 AM - 4:00 AM" (info status).- "Third-party CDN maintenance window" (info status).
During the maintenance window, the component shows an info status. After the window ends, it returns to its previous status.
**No automatic monitoring:**Static components do not perform any health checks or generate incidents. You are responsible for:- Monitoring the service through other means.- Creating status reports when issues occur.- Updating reports when issues are resolved.- Communicating maintenance windows in advance.
**Status hierarchy:**
1. **Error** — a status report with a `major_outage` [impact](/docs/reference/status-report#component-impacts).2. **Degraded** — other unresolved status reports affecting this component.3. **Info** — ongoing scheduled maintenance.4. **Success** — no active reports or maintenances.
**What affects static components:**
- Manual status reports.- Scheduled maintenances.- Automatic incidents are **not** supported.
## Component groups
Component groups allow you to organize related page components into logical sections on your status page. Groups improve readability and help visitors understand your service architecture.
**Benefits:**- Visual organization of related services.- Collapsible sections for better page structure.- Independent ordering within groups.- Clear service categorization.
**Examples of grouping strategies:**
| Group name | Components ||------------|------------|| **API Services** | Authentication API, Data API, WebSocket API || **Infrastructure** | Database, Cache, Message Queue || **External Dependencies** | Payment Provider, Email Service, CDN || **Regional Services** | US Region, EU Region, APAC Region |
**Group configuration:**
- **Name** — the group heading displayed on your status page.- **Default open** — whether the group renders expanded on first load. Defaults to collapsed.- **Components** — the page components contained within this group, ordered independently.
A group has no order field of its own. Its position among other groups and ungrouped components is derived from the lowest display order of the components inside it.
## Events and status
Page components can be affected by up to three types of events that influence their displayed status. The type of component determines which events apply:
| Event type | Monitor components | Static components ||------------|-------------------|-------------------|| **Incidents** | Automatic | Not supported || **Status reports** | Manual | Manual || **Maintenances** | Manual | Manual |
### Incidents
**Applies to:** monitor components only.
Incidents are automatically generated when a monitor detects a failure. They represent unplanned outages or degraded performance discovered through active monitoring.
**How incidents are created:**
- Monitor check fails (connection timeout, HTTP error, DNS failure).- Monitor assertion fails (wrong status code, unexpected response body).- Monitor reaches degraded threshold (response time too slow).
**Status impact:** components with active incidents show an **error** status. This takes the highest priority in the status hierarchy.
**Resolution:** incidents are automatically resolved when the monitor recovers and checks succeed again.
<Aside>Static components **never** generate incidents because they are not linked to monitors. Use status reports for manual issue tracking on static components.</Aside>
### Status reports
**Applies to:** both monitor and static components.
Status reports are manually created updates about component health or issues. They provide a way to communicate problems that may not trigger automatic monitoring or to manually report issues with static components.
**Status impact:** each report update can set a per-component [impact level](/docs/reference/status-report#component-impacts) (`degraded_performance`, `partial_outage`, `major_outage`). A component with an active `major_outage` impact shows an **error** status; the other non-operational impacts show **degraded**. Reports without impact levels show a **degraded** status while unresolved.
**Use cases for monitor components:**
- Reporting known issues that don't cause complete outages.- Communicating performance degradation not captured by monitoring.- Providing context for intermittent issues.
**Use cases for static components:**
- Reporting third-party service issues (e.g., "Stripe processing delays").- Communicating external service degradation.- Announcing partial outages of non-monitored systems.
**Attaching to components:** when creating a status report, you can select which components are affected. Multiple components can be attached to a single report.
### Maintenances
**Applies to:** both monitor and static components.
Maintenances are scheduled maintenance windows that you create in advance. They inform visitors about planned downtime or service interruptions for both monitored and static components.
**Status impact:** components with ongoing maintenances show an **info** status (unless overridden by incidents or reports).
**Use cases for monitor components:**
- Scheduled system upgrades that will cause downtime.- Infrastructure changes that affect monitored services.- Planned deployments requiring service restarts.
**Use cases for static components:**
- Third-party maintenance windows (e.g., "Payment provider scheduled maintenance").- External service upgrade notifications.- Planned downtime for non-monitored dependencies.
**Scheduling:** maintenances have a defined start and end time. The info status automatically appears during the window and disappears when the maintenance ends.
**Attaching to components:** when creating a maintenance, you select which components will be affected. This lets you communicate maintenance impact across multiple services.
## Managing components
### Adding components
You can add components to your status page in two ways:
1. **Individual components:** Add a single component outside of any group.2. **Components within groups:** Add a component directly into a new or existing group.
When adding a monitor component, you can only select from monitors that:- Are currently active.- Have not been deleted.- Are not already linked to another component on this status page.
### Reordering components
Components and groups can be reordered using drag-and-drop functionality in the dashboard. The order determines how they appear on your status page from top to bottom.
**Ordering tips:**
- Place your most critical services at the top.- Group related services together.- Consider visitor priorities when ordering.
### Editing components
You can modify the following properties of existing components:
- Component name and description.- Group assignment (move between groups or make ungrouped).- Display order.
**Note:** you cannot change a component's type (monitor to static or vice versa) after creation. To change types, delete the component and create a new one.
### Deleting components
When you delete a component, any associations with status reports and maintenances are automatically removed. The linked monitor (if applicable) is not deleted and remains available in your workspace.
**Warning:** deletion is permanent and cannot be undone. Ensure you want to remove the component before confirming deletion.
## Deprecation notice
The legacy monitor-only system for status pages is deprecated in favour of the more flexible page component system.
**Deprecated approach:**
- Status pages directly referenced monitors.- No support for static content.- Limited organisational flexibility.
**Current approach (page components):**
- Status pages contain page components.- Components can be monitors or static content.- Full support for grouping and custom ordering.- Better separation between monitoring and status page presentation.
### API compatibility
**v1 API (backward compatibility):** the v1 API continues to display `monitorIds` and `monitors` fields in status page responses to avoid breaking changes for existing integrations. However, these fields now only include page components that are explicitly of type `monitor`. Static components are not included in these legacy fields.
**Future API versions:** newer API versions will primarily use the `pageComponents` structure. The legacy `monitors` and `monitorIds` fields will be removed in future API versions. We recommend migrating your integrations to use `pageComponents` for full feature support.
## Related resources
- **[Status page reference](/docs/reference/status-page)** — complete status page configuration reference.- **[Status report reference](/docs/reference/status-report)** — details on creating and managing status reports.- **[Create a status page](/docs/tutorial/create-your-first-status-page)** — step-by-step tutorial on creating a status page.- **[HTTP monitor reference](/docs/reference/http-monitor)** — technical specification for HTTP monitors that can be linked to components.