openstatus.dev
Openstatus
www.openstatus.dev
Improve documentation with Diátaxis framework (#1702)
* Initial plan
* Improve docs structure with Diátaxis framework
Co-authored-by: thibaultleouay <13894054+thibaultleouay@users.noreply.github.com>
* Enhance tutorials, guides, and explanations with better structure
Co-authored-by: thibaultleouay <13894054+thibaultleouay@users.noreply.github.com>
* Improve CLI tutorial and monitoring-as-code explanation
Co-authored-by: thibaultleouay <13894054+thibaultleouay@users.noreply.github.com>
* Enhance reference docs and GitHub Actions guide
Co-authored-by: thibaultleouay <13894054+thibaultleouay@users.noreply.github.com>
* fix docs
* remove old docs
* remove emdash
* more docs
* improve reference part
---------
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: thibaultleouay <13894054+thibaultleouay@users.noreply.github.com>
Co-authored-by: Thibault Le Ouay Ducasse <thibaultleouay@gmail.com>
authored by
Copilot
thibaultleouay
copilot-swe-agent[bot]
Thibault Le Ouay Ducasse
and committed by
GitHub
411711c8
510e2f9a
+1971
-1569
+91
GEMINI.md
+91
GEMINI.md
···
1
+
# GEMINI.md
2
+
3
+
This file provides a comprehensive overview of the OpenStatus project, its architecture, and development conventions to be used as instructional context for future interactions.
4
+
5
+
## Project Overview
6
+
7
+
OpenStatus is an open-source synthetic monitoring platform. It allows users to monitor their websites and APIs from multiple locations and receive notifications when they are down or slow.
8
+
9
+
The project is a monorepo managed with pnpm workspaces and Turborepo. It consists of several applications and packages that work together to provide a complete monitoring solution.
10
+
11
+
### Core Technologies
12
+
13
+
- **Frontend:**
14
+
- Next.js (with Turbopack)
15
+
- React
16
+
- Tailwind CSS
17
+
- shadcn/ui
18
+
- tRPC
19
+
- **Backend:**
20
+
- Hono (Node.js framework)
21
+
- Go
22
+
- **Database:**
23
+
- Turso (libSQL)
24
+
- Drizzle ORM
25
+
- **Data Analytics:**
26
+
- Tinybird
27
+
- **Authentication:**
28
+
- NextAuth.js
29
+
- **Build System:**
30
+
- Turborepo
31
+
32
+
### Architecture
33
+
34
+
The OpenStatus platform is composed of three main applications:
35
+
36
+
- **`apps/dashboard`**: A Next.js application that provides the main user interface for managing monitors, viewing status pages, and configuring notifications.
37
+
- **`apps/server`**: A Hono-based backend server that provides the API for the dashboard application.
38
+
- **`apps/checker`**: A Go application responsible for performing the actual monitoring checks from different locations.
39
+
40
+
These applications are supported by a collection of shared packages in the `packages/` directory, which provide common functionality such as database access, UI components, and utility functions.
41
+
42
+
## Building and Running
43
+
44
+
The project can be run using Docker (recommended) or a manual setup.
45
+
46
+
### With Docker
47
+
48
+
1. Copy the example environment file:
49
+
```sh
50
+
cp .env.docker.example .env.docker
51
+
```
52
+
2. Start all services:
53
+
```sh
54
+
docker compose up -d
55
+
```
56
+
3. Access the applications:
57
+
- Dashboard: `http://localhost:3002`
58
+
- Status Pages: `http://localhost:3003`
59
+
60
+
### Manual Setup
61
+
62
+
1. Install dependencies:
63
+
```sh
64
+
pnpm install
65
+
```
66
+
2. Initialize the development environment:
67
+
```sh
68
+
pnpm dx
69
+
```
70
+
3. Run a specific application:
71
+
```sh
72
+
pnpm dev:dashboard
73
+
pnpm dev:status-page
74
+
pnpm dev:web
75
+
```
76
+
77
+
### Running Tests
78
+
79
+
To run the test suite, use the following command:
80
+
81
+
```sh
82
+
pnpm test
83
+
```
84
+
85
+
## Development Conventions
86
+
87
+
- **Monorepo:** The project is organized as a monorepo using pnpm workspaces. All applications and packages are located in the `apps/` and `packages/` directories, respectively.
88
+
- **Build System:** Turborepo is used to manage the build process. The `turbo.json` file defines the build pipeline and dependencies between tasks.
89
+
- **Linting and Formatting:** The project uses Biome for linting and formatting. The configuration can be found in the `biome.jsonc` file.
90
+
- **Code Generation:** The project uses `drizzle-kit` for database schema migrations.
91
+
- **API:** The backend API is built using Hono and tRPC. The API is documented using OpenAPI.
-35
apps/docs/src/content/docs/alerting/overview.mdx
-35
apps/docs/src/content/docs/alerting/overview.mdx
···
1
-
---
2
-
title: Overview
3
-
description: "Discover the different notification channels available in OpenStatus"
4
-
---
5
-
import { Card } from '@astrojs/starlight/components';
6
-
import { CardGrid } from '@astrojs/starlight/components';
7
-
import { Image } from 'astro:assets';
8
-
import { LinkCard } from '@astrojs/starlight/components';
9
-
import DiscordNotification from '../../../assets/notification/discord-notification.png';
10
-
11
-
If you connect notification channels to your OpenStatus account, you can receive
12
-
alerts when your services are down. We will contact you when an incident is
13
-
created.
14
-
15
-
By default we don't send any notification. You need to connect your monitor to a notification channel to receive alerts.
16
-
17
-
<Image
18
-
src={DiscordNotification}
19
-
alt="Create your notification bot"
20
-
/>
21
-
22
-
## Notification channels
23
-
24
-
<CardGrid>
25
-
<LinkCard title="Email ✉️" href="/alerting/providers/email" description=" Receive an email"/>
26
-
<LinkCard title="Slack 📣" href="/alerting/providers/slack" description="Get notified on Slack" />
27
-
<LinkCard title="Discord 🤖" href="/alerting/providers/discord" description="Get notified on Discord" />
28
-
<LinkCard title="SMS 📱" href="/alerting/providers/sms" description="Receive a text message" />
29
-
<LinkCard title="ntfy.sh 🔔" href="/alerting/providers/ntfy" description="Receive a ntfy.sh notification" />
30
-
<LinkCard title="Pagerduty 📟" href="/alerting/providers/pagerduty" description="Receive a pagerduty notification"/ >
31
-
<LinkCard title="Phone 📞" href="/alerting/providers/phone-call" description="Get called on your phone" />
32
-
<LinkCard title="Telegram 📡" href="/alerting/providers/telegram" description="Get notified on Telegram" />
33
-
<LinkCard title="Webhook 🌐" href="/alerting/providers/webhook" description="Get notified by webhook" />
34
-
35
-
</CardGrid>
-13
apps/docs/src/content/docs/alerting/providers/discord.mdx
-13
apps/docs/src/content/docs/alerting/providers/discord.mdx
···
1
-
---
2
-
title: Discord
3
-
description: "How to set up Discord notifications in OpenStatus to get alerts when your synthetic check fail"
4
-
---
5
-
6
-
When a monitor is down you can set up a webhook to send a message to a Discord
7
-
channel. You can set up a webhook in the Discord settings. The webhook URL
8
-
should look something like this:
9
-
`https://discordapp.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz1234567890`
10
-
11
-
## How to set up your Discord webhook
12
-
13
-
https://support.discord.com/hc/en-us/articles/228383668
-7
apps/docs/src/content/docs/alerting/providers/email.mdx
-7
apps/docs/src/content/docs/alerting/providers/email.mdx
-12
apps/docs/src/content/docs/alerting/providers/ntfy.mdx
-12
apps/docs/src/content/docs/alerting/providers/ntfy.mdx
···
1
-
---
2
-
title: ntfy.sh
3
-
description: "How to set up ntfy.sh notifications in OpenStatus to get alerts when your synthetic check fail"
4
-
---
5
-
6
-
[ntfy.sh](https://ntfy.sh/) is an open-source servicer that allows you to receive push notifications on your phone.
7
-
8
-
9
-
10
-
Go to the Notifications Page . Select `ntfy.sh` from the list of available integrations.
11
-
12
-
Enter your ntfy topic (required), your custom server URL, and your bearer token.
-69
apps/docs/src/content/docs/alerting/providers/opsgenie.mdx
-69
apps/docs/src/content/docs/alerting/providers/opsgenie.mdx
···
1
-
---
2
-
title: OpsGenie
3
-
description: "How to set up OpsGenie notifications in OpenStatus to get alerts when your synthetic check fail"
4
-
5
-
---
6
-
import { Image} from 'astro:assets';
7
-
import OpsGenie1 from '../../../../assets/notification/opsgenie/opsgenie-1.png';
8
-
import OpsGenie2 from '../../../../assets/notification/opsgenie/opsgenie-2.png';
9
-
import OpsGenie3 from '../../../../assets/notification/opsgenie/opsgenie-3.png';
10
-
import OpsGenie4 from '../../../../assets/notification/opsgenie/opsgenie-4.png';
11
-
import OpsGenie5 from '../../../../assets/notification/opsgenie/opsgenie-5.png';
12
-
13
-
Get Notified on OpsGenie when we create an incident.
14
-
15
-
## How to connect OpsGenie
16
-
17
-
### Create an OpsGenie Integration
18
-
19
-
First we need to create an integration in OpsGenie.
20
-
21
-
Go to your team in OpsGenie and select `Integrations` from the menu.
22
-
23
-
24
-
<Image
25
-
src={OpsGenie1}
26
-
alt="OpsGenie integration page"
27
-
/>
28
-
In the integrations page, search for `API` and select it.
29
-
30
-
31
-
<Image
32
-
src={OpsGenie2}
33
-
alt="Connect to OpsGenie"
34
-
/>
35
-
36
-
Give your integration a name and save it.
37
-
Copy your API key and save it. You will need it to connect OpenStatus to OpsGenie.
38
-
39
-
<Image
40
-
src={OpsGenie3}
41
-
alt="Connect to OpsGenie"
42
-
/>
43
-
44
-
45
-
### Connect your OpenStatus account to OpsGenie
46
-
47
-
48
-
Go to the Alerts Page . Select `OpsGenie` from the list of available integrations.
49
-
50
-
51
-
<Image
52
-
src={OpsGenie4}
53
-
alt="OpenStatus Notifications Page"
54
-
/>
55
-
56
-
57
-
Give you integration a name and paste the API key you copied from OpsGenie and select the region of your OpsGenie account.
58
-
59
-
<Image
60
-
src={OpsGenie5}
61
-
alt="Connect to OpsGenie in OpenStatus"
62
-
/>
63
-
64
-
Select the service you want to use to send notifications. You can create a new service if you don't have one.
65
-
66
-
67
-
You are now connected to OpsGenie.
68
-
69
-
You will receive some notifications if we detect an incident
-41
apps/docs/src/content/docs/alerting/providers/pagerduty.mdx
-41
apps/docs/src/content/docs/alerting/providers/pagerduty.mdx
···
1
-
---
2
-
title: PagerDuty
3
-
description: "How to set up PagerDuty notifications in OpenStatus to get alerts when your synthetic check fail"
4
-
5
-
---
6
-
import { Image} from 'astro:assets';
7
-
import PagerDuty1 from '../../../../assets/notification/pagerduty/pagerduty-1.png';
8
-
import PagerDuty2 from '../../../../assets/notification/pagerduty/pagerduty-2.png';
9
-
import PagerDuty3 from '../../../../assets/notification/pagerduty/pagerduty-3.png';
10
-
11
-
Get Notified on PagerDuty when we create an incident.
12
-
13
-
## How to connect PagerDuty
14
-
15
-
Go to the Notifications Page . Select `PagerDuty` from the list of available integrations.
16
-
17
-
18
-
19
-
<Image
20
-
src={PagerDuty1}
21
-
alt="Connect to PagerDuty"
22
-
/>
23
-
24
-
You will be redirected to the PagerDuty website to authorize OpenStatus to send notifications to your account.
25
-
26
-
<Image
27
-
src={PagerDuty3}
28
-
alt="Connect to PagerDuty"
29
-
/>
30
-
31
-
32
-
Select the service you want to use to send notifications. You can create a new service if you don't have one.
33
-
34
-
<Image
35
-
src={PagerDuty2}
36
-
alt="Connect to PagerDuty"
37
-
/>
38
-
39
-
You are now connected to PagerDuty. Give your integration a name and save it.
40
-
41
-
You will receive some notifications if we detect an incident
-9
apps/docs/src/content/docs/alerting/providers/phone-call.mdx
-9
apps/docs/src/content/docs/alerting/providers/phone-call.mdx
-9
apps/docs/src/content/docs/alerting/providers/slack.mdx
-9
apps/docs/src/content/docs/alerting/providers/slack.mdx
···
1
-
---
2
-
title: Slack
3
-
description: "How to set up Slack notifications in OpenStatus to get alerts when your synthetic check fail"
4
-
5
-
---
6
-
7
-
When a monitor is down, a message can be sent to a Slack channel. To enable this
8
-
feature, you need to create a Slack webhook. You can do this by following the
9
-
instructions [here](https://api.slack.com/incoming-webhooks).
-8
apps/docs/src/content/docs/alerting/providers/sms.mdx
-8
apps/docs/src/content/docs/alerting/providers/sms.mdx
-7
apps/docs/src/content/docs/alerting/providers/telegram.mdx
-7
apps/docs/src/content/docs/alerting/providers/telegram.mdx
-101
apps/docs/src/content/docs/alerting/providers/webhook.mdx
-101
apps/docs/src/content/docs/alerting/providers/webhook.mdx
···
1
-
---
2
-
title: Webhook
3
-
description: "How to set up Webhook notifications in OpenStatus to get alerts when your synthetic check fail"
4
-
---
5
-
## Setting Up Webhook Notifications
6
-
To set up Webhook notifications, follow these steps:
7
-
8
-
1. **Access the Notifications Tab**\
9
-
Navigate to your notifications tab within the application.
10
-
11
-
2. **Add a New Notification**\
12
-
Click on the "Add Notification" button and select Webhook as the notification type.
13
-
14
-
3. **Provide Notification URL**\
15
-
Enter the URL where OpenStatus will send the notification payload. This URL should be publicly accessible and capable of handling incoming POST requests.
16
-
17
-
4. **Optional: Add Custom Headers**\
18
-
If needed, you can include custom headers in your request for additional context or authentication.
19
-
20
-
21
-
## Notification Payloads
22
-
23
-
24
-
OpenStatus sends different payloads depending on the status of the monitor. Below are the payload structures for both
25
-
recovery and failure notifications.
26
-
27
-
28
-
### Payload for Monitor Recovery
29
-
When the monitor recovers, you will receive a notification with the following payload:
30
-
```json
31
-
{
32
-
"monitor": {
33
-
"id": 1,
34
-
"name": "test",
35
-
"url": "http://openstat.us"
36
-
},
37
-
"cronTimestamp": 1744023705307,
38
-
"status": "recovered",
39
-
"statusCode": 200,
40
-
"latency": 1337
41
-
}
42
-
```
43
-
44
-
45
-
Fields Explanation:
46
-
- monitor: Contains details about the monitor.
47
-
- id: Unique identifier for the monitor.
48
-
- name: Name of the monitor.
49
-
- url: The URL being monitored.
50
-
- cronTimestamp: The timestamp when the check was executed, in milliseconds since epoch.
51
-
- status: Indicates the current status of the monitor (in this case, "recovered").
52
-
- statusCode: The HTTP status code returned by the monitored service.
53
-
- latency: The time taken to complete the check, in milliseconds.
54
-
55
-
56
-
### Payload for Monitor Failure
57
-
58
-
In the event of a monitor failure, the notification will include the following payload:
59
-
```json
60
-
{
61
-
"monitor": {
62
-
"id": 1,
63
-
"name": "test",
64
-
"url": "http://openstat.us"
65
-
},
66
-
"cronTimestamp": 1744023705307,
67
-
"status": "error",
68
-
"errorMessage": "Connection refused"
69
-
}
70
-
```
71
-
72
-
Fields Explanation:
73
-
74
-
- monitor: Contains details about the monitor.
75
-
- id: Unique identifier for the monitor.
76
-
- name: Name of the monitor.
77
-
- url: The URL being monitored.
78
-
- cronTimestamp: The timestamp when the check was executed, in milliseconds since epoch.
79
-
- status: Indicates the current status of the monitor (in this case, "error").
80
-
- errorMessage: A description of the error encountered during the check.
81
-
82
-
83
-
### Zod Schema
84
-
85
-
86
-
```ts
87
-
import { z } from "zod";
88
-
89
-
export const PayloadSchema = z.object({
90
-
monitor: z.object({
91
-
id: z.number(),
92
-
name: z.string(),
93
-
url: z.string(),
94
-
}),
95
-
cronTimestamp: z.number(),
96
-
status: z.enum(["degraded", "error", "recovered"]),
97
-
statusCode: z.number().optional(),
98
-
latency: z.number().optional(),
99
-
errorMessage: z.string().optional(),
100
-
});
101
-
````
+57
-3
apps/docs/src/content/docs/concept/best-practices-status-page.mdx
+57
-3
apps/docs/src/content/docs/concept/best-practices-status-page.mdx
···
1
1
---
2
2
title: Best Practices for Status Pages
3
+
description: "How to communicate effectively during incidents and build user trust through transparency"
3
4
---
4
5
5
6
···
22
23
+------------------------------------------------+
23
24
```
24
25
25
-
Status pages are essential tools for communicating service health and incidents to users. They build trust by providing transparency and should be a core component of any software company's communication strategy. Following a set of best practices ensures your status page is effective and helpful.
26
+
## Why status pages matter
27
+
28
+
Status pages are essential tools for communicating service health and incidents to users. They build trust by providing transparency and should be a core component of any software company's communication strategy.
29
+
30
+
When done right, status pages:
31
+
- **Reduce support burden**: Users self-serve incident information
32
+
- **Build trust**: Transparency demonstrates accountability
33
+
- **Improve communication**: Centralized, consistent incident updates
34
+
- **Demonstrate professionalism**: Shows you take reliability seriously
35
+
36
+
Following a set of best practices ensures your status page is effective and helpful.
26
37
27
38
28
39
···
67
78
- **Resolved:** "The issue has been resolved, and all services are now operational."
68
79
69
80
70
-
### Make it Easily Accessible
81
+
### Make it easily accessible
71
82
72
83
Your status page should be easy to find.
73
84
···
75
86
76
87
- **Custom Domain:** Use a simple, memorable URL like status.yourcompany.com.
77
88
89
+
## Advanced considerations
90
+
91
+
### Scheduled maintenance
92
+
93
+
Communicate planned downtime in advance:
94
+
- Announce maintenance at least 72 hours ahead
95
+
- Show maintenance windows on the status page
96
+
- Send reminders 24 hours before maintenance
78
97
79
-
Following these practices turns your status page from a passive communication tool into an active driver of customer trust and confidence.
98
+
### Historical data
99
+
100
+
Show your track record:
101
+
- Display uptime percentages (30/60/90 days)
102
+
- Link to past incidents and post-mortems
103
+
- Be honest about past issues-it builds trust
104
+
105
+
### Subscriber notifications
106
+
107
+
Let users opt in to updates:
108
+
- Email notifications for incidents
109
+
- SMS for critical alerts (if available)
110
+
- RSS/Atom feeds for automated monitoring
111
+
112
+
## Common mistakes to avoid
113
+
114
+
1. **Over-promising uptime**: Don't claim 100% uptime if you haven't achieved it
115
+
2. **Hiding incidents**: Transparency beats saving face
116
+
3. **Technical jargon**: Write for non-technical audiences
117
+
4. **Infrequent updates**: During incidents, update every 30-60 minutes
118
+
5. **Separate status page hosting**: Your status page should work even when your service is down
119
+
120
+
## Implementing with openstatus
121
+
122
+
openstatus makes following these best practices easy:
123
+
124
+
- **[Create a status page](/tutorial/how-to-create-status-page)** - Quick setup
125
+
- **[Configure your page](/tutorial/how-to-configure-status-page)** - Customize appearance
126
+
- **[Set up notifications](/monitoring/customization/notification)** - Alert your team
127
+
- **[Understand uptime calculations](/concept/uptime-calculation-and-values)** - Transparent metrics
128
+
129
+
## Next steps
130
+
131
+
- **[Create your status page](/tutorial/how-to-create-status-page)** - Put these practices into action
132
+
- **[Understanding uptime monitoring](/concept/uptime-monitoring)** - Monitor what you communicate
133
+
- **[Status page reference](/reference/status-page)** - Technical configuration options
+30
-6
apps/docs/src/content/docs/concept/getting-started.mdx
+30
-6
apps/docs/src/content/docs/concept/getting-started.mdx
···
1
1
---
2
-
title: Getting Started
2
+
title: Understanding openstatus
3
+
description: Deep dive into the concepts, architecture, and design decisions behind openstatus
4
+
sidebar:
5
+
label: Getting Started
6
+
order: 1
3
7
---
4
8
9
+
## 💡 Concepts
5
10
6
-
Here’s some content to help you get started with the concept behind OpenStatus.
11
+
### What you'll find here
7
12
8
-
- [Uptime Monitoring](/concept/uptime-monitoring)
9
-
- [Best Practices for Status Pages](/concept/best-practices-status-page)
10
-
- [Uptime Monitoring as Code](/concept/uptime-monitoring-as-code)
11
-
- [Latency vs Response Time](/concept/latency-vs-response-time)
13
+
Our docs help you:
14
+
- Understand core monitoring concepts
15
+
- Learn best practices and design patterns
16
+
- Make informed decisions about your monitoring strategy
17
+
- Appreciate the reasoning behind openstatus features
18
+
19
+
### Core Concepts
20
+
21
+
Build a solid foundation:
22
+
23
+
- **[Uptime Monitoring](/concept/uptime-monitoring)** - What uptime monitoring is, why it matters, and how it works
24
+
- **[Uptime Calculation and Values](/concept/uptime-calculation-and-values)** - How uptime percentages are calculated and what they really mean
25
+
- **[Latency vs Response Time](/concept/latency-vs-response-time)** - Understanding the difference between these crucial metrics
26
+
27
+
### Best Practices
28
+
29
+
Learn from experience:
30
+
31
+
- **[Best Practices for Status Pages](/concept/best-practices-status-page)** - How to communicate effectively during incidents and maintain user trust
32
+
- **[Uptime Monitoring as Code](/concept/uptime-monitoring-as-code)** - Why and how to manage monitoring configuration as code
33
+
34
+
35
+
Have questions or want to discuss these concepts? [Join our community](/help/support/) and share your thoughts!
+59
-4
apps/docs/src/content/docs/concept/latency-vs-response-time.mdx
+59
-4
apps/docs/src/content/docs/concept/latency-vs-response-time.mdx
···
1
1
---
2
-
title: Latency vs Response Time for a request
2
+
title: Understanding Latency vs Response Time
3
+
description: "Deep dive into the difference between latency and response time, and why both matter for monitoring"
3
4
---
4
5
5
-
Latency and response time are two different metrics used in uptime monitoring. Latency measures the time it takes for a request to travel from the probes to the server and back. Response time is the time it takes for the server to process the request and send back a response, plus the latency.
6
+
## The confusion
7
+
8
+
Latency and response time are often used interchangeably, but they measure different things. Understanding the distinction is crucial for effective monitoring and performance optimization.
9
+
10
+
**The key difference:**
11
+
- **Latency** measures network travel time
12
+
- **Response time** measures total time including server processing
6
13
7
-
## What is Latency?
14
+
Both metrics matter, but for different reasons.
15
+
16
+
## What is latency?
17
+
18
+
Latency and response time are two different metrics used in uptime monitoring. Latency measures the time it takes for a request to travel from the probes to the server and back. Response time is the time it takes for the server to process the request and send back a response, plus the latency.
8
19
9
20
```
10
21
openstatus Network Server (Website)
···
58
69
A high response time often indicates a problem with the server-side application itself. For example, slow database queries or inefficient can dramatically increase the response time, even if the network latency is low.
59
70
60
71
61
-
## Why the Distinction Matters for Uptime Monitoring
72
+
## Why the distinction matters for uptime monitoring
62
73
63
74
Understanding the difference between these two metrics is crucial for diagnosing performance issues.
64
75
···
69
80
- **Response time is the ultimate measure of user experience** because it reflects the full journey of a request. Users don't just care how fast a packet can get to the server; they care how long it takes to see the results.
70
81
71
82
By monitoring both metrics, you can quickly pinpoint whether a performance slowdown is caused by your application or by the network.
83
+
84
+
## Practical implications
85
+
86
+
### For monitoring strategy
87
+
88
+
- **Monitor both metrics**: Don't rely on just one
89
+
- **Set appropriate thresholds**: Latency thresholds should be lower than response time thresholds
90
+
- **Consider geographic factors**: Latency varies by monitoring location
91
+
- **Track trends**: Sudden changes in either metric indicate issues
92
+
93
+
### For optimization
94
+
95
+
- **Reduce latency**: Use CDNs, optimize routing, choose closer hosting
96
+
- **Improve response time**: Optimize code, database queries, caching
97
+
- **User location matters**: Users far from your server will always see higher latency
98
+
99
+
### Common scenarios
100
+
101
+
**Scenario 1: Consistent latency, variable response time**
102
+
- Indicates server-side performance issues
103
+
- Look at: Database queries, API calls, resource utilization
104
+
105
+
**Scenario 2: High latency from specific regions**
106
+
- Indicates geographic network issues
107
+
- Solution: Add regional monitoring points or CDN
108
+
109
+
**Scenario 3: Both metrics degrading**
110
+
- Could be network saturation or DDoS attack
111
+
- Check: Network bandwidth, traffic patterns, security
112
+
113
+
## What openstatus tracks
114
+
115
+
openstatus monitors and displays:
116
+
- **Total response time**: The complete user experience
117
+
- **Detailed timing breakdown**: DNS, TCP, TLS, request, response
118
+
- **Regional differences**: Compare performance across locations
119
+
- **Historical trends**: Identify patterns over time
120
+
121
+
## Next steps
122
+
123
+
- **[Create your first monitor](/tutorial/how-to-create-monitor)** - Start tracking these metrics
124
+
- **[Understanding uptime monitoring](/concept/uptime-monitoring)** - Broader monitoring concepts
125
+
- **[Monitor data collected](/monitoring/monitor-data-collected)** - All metrics we track
126
+
- **[HTTP monitor reference](/reference/http-monitor)** - Technical specifications
+2
-2
apps/docs/src/content/docs/concept/uptime-calculation-and-values.mdx
+2
-2
apps/docs/src/content/docs/concept/uptime-calculation-and-values.mdx
···
65
65
## Manual Type
66
66
67
67
The manual type is for teams who want to **fully control what’s shown** on your status page, without relying on automatic checks.
68
-
By default, your monitor is marked operational. You can then manually create status reports whenever you want to reflect changes — independent of any monitoring data.
68
+
By default, your monitor is marked operational. You can then manually create status reports whenever you want to reflect changes - independent of any monitoring data.
69
69
70
70
This is ideal if:
71
71
- you don’t have synthetic monitoring set up yet,
···
75
75
76
76
In simple terms: `uptime = (total duration - status report duration) / total duration`
77
77
78
-
> **Note**: the values you are defining are attached to a status page. You cannot change them per monitor (for now).
78
+
> **Note**: the values you are defining are attached to a status page. You cannot change them per monitor (for now).
+41
-5
apps/docs/src/content/docs/concept/uptime-monitoring-as-code.mdx
+41
-5
apps/docs/src/content/docs/concept/uptime-monitoring-as-code.mdx
···
1
1
---
2
-
title: Uptime Monitoring as Code
2
+
title: Understanding Monitoring as Code
3
+
description: "Why and how to manage monitoring configuration as code for GitOps workflows"
3
4
---
4
5
import { Code } from '@astrojs/starlight/components';
6
+
7
+
## The traditional approach (and its problems)
8
+
9
+
Traditionally, monitoring is configured through web dashboards:
10
+
1. Log into a web interface
11
+
2. Click through forms to create monitors
12
+
3. Manually replicate configuration across environments
13
+
4. No audit trail of who changed what
14
+
5. Difficult to review changes before they go live
15
+
16
+
This works for small teams with few monitors, but doesn't scale.
17
+
18
+
## What is monitoring as code?
19
+
20
+
**Monitoring as Code** treats your monitoring configuration the same way you treat your application code: as text files that can be versioned, reviewed, and deployed through automated pipelines.
21
+
22
+
Instead of clicking buttons, you define monitors in YAML:
23
+
5
24
export const code = `
6
25
# yaml-language-server: $schema=https://www.openstatus.dev/schema.json
7
26
uptime-monitor:
···
21
40
url: https://openstat.us
22
41
method: GET
23
42
headers:
24
-
User-Agent: OpenStatus
43
+
User-Agent: openstatus
25
44
assertions:
26
45
- kind: statusCode
27
46
compare: eq
···
44
63
url: https://api.github.com/graphql
45
64
method: POST
46
65
headers:
47
-
User-Agent: OpenStatus
66
+
User-Agent: openstatus
48
67
Authorization: Bearer YOUR_TOKEN_HERE
49
68
body: |
50
69
{
···
52
71
}
53
72
`
54
73
55
-
Uptime monitoring is a vital part of any robust system, ensuring your services are online and available to users. Historically, this has involved manually configuring monitors through a web interface, which can be tedious and prone to human error. Uptime Monitoring as Code changes this by treating your monitoring configurations like any other part of your application—as code.
74
+
Uptime monitoring is a vital part of any robust system, ensuring your services are online and available to users. Historically, this has involved manually configuring monitors through a web interface, which can be tedious and prone to human error. Uptime Monitoring as Code changes this by treating your monitoring configurations like any other part of your application-as code.
56
75
57
76
58
77
## Why Use Uptime Monitoring as Code?
···
80
99
81
100
### Making Changes with the CLI
82
101
83
-
Once your `openstatus.yaml` file is ready, you use our [command-line interface (CLI)](/tutorial/get-started-with-openstatus-cli) to apply the changes. The CLI compares your local configuration with the current state of your monitors and applies only the necessary changes—creating new monitors, updating existing ones, or deleting those no longer defined.
102
+
Once your `openstatus.yaml` file is ready, you use our [command-line interface (CLI)](/tutorial/get-started-with-openstatus-cli) to apply the changes. The CLI compares your local configuration with the current state of your monitors and applies only the necessary changes creating new monitors, updating existing ones, or deleting those no longer defined.
84
103
85
104
**Common CLI Commands:**
86
105
···
88
107
- `openstatus monitors import`: Import the monitors from your dashboard to a new `openstatus.yaml` file.
89
108
90
109
By integrating this **Uptime Monitoring as Code** workflow into your development lifecycle, you can achieve a more reliable, consistent, and scalable system. It's about moving from manual clicks to automated, version-controlled operations.
110
+
111
+
## Best practices
112
+
113
+
1. **Start simple**: Begin with a few monitors, expand as you learn
114
+
2. **Use templates**: Create reusable patterns for common monitor types
115
+
3. **Environment variables**: Use secrets management for tokens and sensitive data
116
+
4. **Review changes**: Always review diffs before applying
117
+
5. **Document decisions**: Use commit messages to explain "why"
118
+
119
+
## Next steps
120
+
121
+
Ready to implement monitoring as code?
122
+
123
+
- **[Get Started with CLI](/tutorial/get-started-with-openstatus-cli)** - Install and configure the CLI
124
+
- **[Monitor Your MCP Server](/guides/how-to-monitor-mcp-server/)** - Real-world example
125
+
- **[CLI Reference](/reference/cli-reference)** - Complete command documentation
126
+
- **[YAML Examples](https://github.com/openstatusHQ/cli-template)** - Sample configurations
+48
-2
apps/docs/src/content/docs/concept/uptime-monitoring.mdx
+48
-2
apps/docs/src/content/docs/concept/uptime-monitoring.mdx
···
1
1
---
2
-
title: About Uptime Monitoring
2
+
title: Understanding Uptime Monitoring
3
+
description: A deep dive into uptime monitoring concepts, architecture, and best practices
3
4
---
5
+
6
+
## What is uptime monitoring?
7
+
4
8
The concept of **uptime monitoring** refers to the practice of continuously checking the availability of a website, server, or application. It's a proactive measure that alerts you to problems as they happen, helping to minimize downtime and its potential negative impacts.
9
+
10
+
Uptime monitoring is fundamentally about answering three questions:
11
+
1. **Is my service available?** Can users reach it?
12
+
2. **Is it performing well?** Are response times acceptable?
13
+
3. **Is it functioning correctly?** Is it returning the expected data?
5
14
6
15
7
16
```
···
88
97
89
98
- **Integrations:** Connect with your existing tools like Slack, PagerDuty, or email.
90
99
91
-
3. **Establish Alerting Rules:** Determine who should be notified and when. Set up an escalation policy—for example, if a primary on-call engineer doesn't respond within 15 minutes, the alert is sent to a manager.
100
+
3. **Establish Alerting Rules:** Determine who should be notified and when. Set up an escalation policy, for example, if a primary on-call engineer doesn't respond within 15 minutes, the alert is sent to a manager.
92
101
93
102
4. **Regularly Review and Optimize:** Monitor your monitoring system itself. Review historical data to identify recurring issues, fine-tune alert thresholds, and update your list of monitored services as your infrastructure evolves.
103
+
104
+
## The human factor
105
+
106
+
While uptime monitoring is largely automated, it's important to remember the human aspects:
107
+
108
+
- **Alert fatigue**: Too many false positives can lead teams to ignore alerts. Fine-tune your monitoring to reduce noise.
109
+
- **On-call burden**: Distribute monitoring responsibilities fairly and ensure adequate coverage.
110
+
- **Communication**: During incidents, clear communication with users is as important as technical fixes.
111
+
- **Post-mortems**: Learn from downtime by conducting blameless post-mortems.
112
+
113
+
## Monitoring philosophy
114
+
115
+
Different approaches to monitoring reflect different philosophies:
116
+
117
+
- **Optimistic monitoring**: Assume everything is working unless proven otherwise. Alert on failures.
118
+
- **Pessimistic monitoring**: Assume nothing works unless actively verified. Alert on missing data.
119
+
- **SLI/SLO based**: Monitor Service Level Indicators against defined Service Level Objectives.
120
+
121
+
openstatus supports all these approaches, letting you choose what works best for your team.
122
+
123
+
## Beyond basic availability
124
+
125
+
Modern uptime monitoring goes beyond simple "up or down" checks:
126
+
127
+
- **Performance monitoring**: Track response times and identify degradation before outages.
128
+
- **Geographic monitoring**: Verify availability from multiple regions to catch regional issues.
129
+
- **Synthetic monitoring**: Simulate user journeys to catch functional issues.
130
+
- **Real user monitoring (RUM)**: Complement synthetic checks with actual user experience data.
131
+
132
+
## Next steps
133
+
134
+
Now that you understand uptime monitoring concepts:
135
+
136
+
- **[Get started with a monitor](/tutorial/how-to-create-monitor)** - Apply these concepts in practice
137
+
- **[Learn about uptime calculations](/concept/uptime-calculation-and-values)** - Understand how uptime percentages work
138
+
- **[Best practices for status pages](/concept/best-practices-status-page)** - Communicate effectively during incidents
139
+
- **[Monitoring as Code](/concept/uptime-monitoring-as-code)** - Manage monitoring configuration programmatically
-47
apps/docs/src/content/docs/contributing/getting-started.mdx
-47
apps/docs/src/content/docs/contributing/getting-started.mdx
···
1
-
---
2
-
title: Getting Started
3
-
---
4
-
5
-
6
-
## Setup
7
-
8
-
1. Clone the repository
9
-
10
-
```sh
11
-
git clone https://github.com/openstatushq/openstatus.git
12
-
```
13
-
14
-
2. Install dependencies
15
-
16
-
```sh
17
-
pnpm install
18
-
```
19
-
20
-
3. Initialize the development environment
21
-
22
-
Launch the database in one terminal:
23
-
24
-
```sh
25
-
turso dev --db-file openstatus-dev.db
26
-
```
27
-
28
-
In another terminal, run the following command:
29
-
30
-
```sh
31
-
pnpm dx
32
-
```
33
-
34
-
4. Launch the web app
35
-
36
-
```sh
37
-
pnpm dev:web
38
-
```
39
-
40
-
It will:
41
-
42
-
- run the web app on port `3000`
43
-
44
-
5. See the results:
45
-
46
-
- open [http://localhost:3000](http://localhost:3000) for the web app
47
-
-80
apps/docs/src/content/docs/contributing/requirements.mdx
-80
apps/docs/src/content/docs/contributing/requirements.mdx
···
1
-
---
2
-
title: Requirements
3
-
---
4
-
5
-
import { Aside } from "@astrojs/starlight/components";
6
-
7
-
<Aside>WIP</Aside>
8
-
9
-
## System Requirements
10
-
11
-
Before you start, make sure you have the following applications and their
12
-
minimum versions installed, in addition to Node.js and pnpm (as mentioned
13
-
earlier):
14
-
15
-
- [Node.js 18.0.0](https://nodejs.org/) or later.
16
-
- [pnpm 8.6.2](https://pnpm.io/) or later.
17
-
- macOS, Windows (including WSL), and Linux are supported.
18
-
19
-
## Installing Node.js
20
-
21
-
To install Node.js, follow the instructions based on your operating system:
22
-
23
-
- For Windows or macOS, visit the official Node.js website:
24
-
[https://nodejs.org/](https://nodejs.org/) and download the latest or LTS
25
-
version (18.0.0 or above). Run the installer and follow the setup wizard.
26
-
27
-
- For Linux, you can use a package manager
28
-
([nvm](https://github.com/nvm-sh/nvm.git/)) or download the binaries from the
29
-
official Node.js website. For example, using the package manager `apt` on
30
-
Ubuntu:
31
-
32
-
```bash
33
-
sudo apt update
34
-
sudo apt install nodejs
35
-
```
36
-
37
-
Ensure that the installed version is 18.0.0 or above:
38
-
39
-
```bash
40
-
node --version
41
-
```
42
-
43
-
## Installing pnpm
44
-
45
-
To install pnpm, you can use npm, the Node.js package manager. Open your
46
-
terminal or command prompt and run the following command:
47
-
48
-
```bash
49
-
npm install -g pnpm
50
-
```
51
-
52
-
Make sure that the installed version of pnpm is 8.6.2 or above:
53
-
54
-
```bash
55
-
pnpm --version
56
-
```
57
-
58
-
Alternatively you can also install it from its official website
59
-
[https://pnpm.io/](https://pnpm.io/).
60
-
61
-
## **Optional Requirements for a Local Database:**
62
-
63
-
If you want to use a local database, it is recommended to install "brew" and
64
-
"sqld".
65
-
66
-
### Installing brew
67
-
68
-
To install brew, it is recommended to use brew.sh from
69
-
[https://brew.sh/](https://brew.sh/) and follow its instructions.
70
-
71
-
72
-
### Installing Turso
73
-
74
-
If you want to run Turso locally you can follow the instructions in the
75
-
[Turso CLI](https://docs.turso.tech/reference/turso-cli)
76
-
77
-
78
-
### Installing Bun
79
-
80
-
To install Bun, visit the official website [https://bun.sh/](https://bun.sh/)
-376
apps/docs/src/content/docs/contributing/setup-env.mdx
-376
apps/docs/src/content/docs/contributing/setup-env.mdx
···
1
-
---
2
-
title: Setup environment files
3
-
---
4
-
5
-
import { Aside } from "@astrojs/starlight/components";
6
-
7
-
import { Image } from 'astro:assets';
8
-
9
-
import Drizzle from '../../../assets/setup-env/drizzle-studio.png';
10
-
11
-
<Aside>WIP</Aside>
12
-
13
-
# Configuration of the .env file
14
-
15
-
The `.env` file contains various environment variables that need to be properly
16
-
configured for the application to work correctly. Below, I will explain how to
17
-
obtain the values for some of these variables.
18
-
19
-
## Setting up Resend for sending emails
20
-
21
-
The "RESEND for email" section in the `.env` file contains the "RESEND_API_KEY"
22
-
variable, which corresponds to the Resend API key that you need to set up to
23
-
send emails.
24
-
25
-
Here's how to obtain the Resend API key:
26
-
27
-
1. Access the Resend website at [https://resend.com](https://resend.com) and log
28
-
in with your account or create a new account if you don't have one.
29
-
30
-
2. Once you've logged in, look for the option to add a new API Key. You can do
31
-
this by clicking the corresponding button or navigating to the "API Keys"
32
-
section and creating it from there.
33
-
34
-
3. Fill in the necessary information to create the API Key, such as the name and
35
-
required permissions.
36
-
37
-
4. Once the API Key is created, copy its value, which usually starts with "re\_"
38
-
and includes a series of characters.
39
-
40
-
5. Paste this API Key value into the `.env` file under the "RESEND_API_KEY"
41
-
variable. It should look something like this (real values without
42
-
censorship):
43
-
44
-
45
-
46
-
```
47
-
# RESEND for email
48
-
RESEND_API_KEY=re_••••••••••••••••••••••••••••••••
49
-
```
50
-
51
-
Replace the key with the actual Resend API key you obtained from your Resend
52
-
account.
53
-
54
-
## Setting up Upstash (QStash and Redis)
55
-
56
-
The "Upstash for queue" section in the `.env` file contains the following
57
-
variables related to QStash and Redis:
58
-
59
-
```
60
-
# UPSTASH for queue
61
-
QSTASH_CURRENT_SIGNING_KEY=qstash-current-signing-key
62
-
QSTASH_NEXT_SIGNING_KEY=qstash-next-signing-key
63
-
QSTASH_TOKEN=qstash-token
64
-
QSTASH_URL=https://qstash.upstash.io/v1/publish/
65
-
66
-
67
-
# UPSTASH redis for waiting list
68
-
UPSTASH_REDIS_REST_URL=test
69
-
UPSTASH_REDIS_REST_TOKEN=test
70
-
```
71
-
72
-
To configure UPSTASH correctly, follow these steps:
73
-
74
-
### Obtaining QStash Keys
75
-
76
-
1. Log in to your UPSTASH account at
77
-
[https://upstash.com/](https://upstash.com/) or create a new account if you
78
-
don't have one yet.
79
-
80
-
2. Once logged in, go to
81
-
[https://console.upstash.com/qstash](https://console.upstash.com/qstash) and
82
-
copy the keys you need one by one. These keys are
83
-
"QSTASH_CURRENT_SIGNING_KEY", "QSTASH_NEXT_SIGNING_KEY", and "QSTASH_TOKEN".
84
-
85
-
3. Paste these keys into the `.env` file under their respective variables. It
86
-
should look something like this (real values without censorship):
87
-
88
-
```
89
-
# UPSTASH for queue
90
-
QSTASH_CURRENT_SIGNING_KEY=sig_•••••••••••••••••••••••••
91
-
QSTASH_NEXT_SIGNING_KEY=sig_•••••••••••••••••••••••••
92
-
QSTASH_TOKEN=ey••••••••••••••••••••••••••••••••
93
-
QSTASH_URL=https://qstash.upstash.io/v1/publish/
94
-
```
95
-
96
-
Replace the ellipsis with the actual keys you obtained from UPSTASH.
97
-
98
-
### Configuring Redis
99
-
100
-
> We have been using Redis for the waiting list in this project. It is not used
101
-
> currently. However, if you want to use it, you can follow the steps below to.
102
-
103
-
1. Create a Redis database in UPSTASH through
104
-
[https://console.upstash.com/](https://console.upstash.com/).
105
-
106
-
2. Once the database is created, access "Details" and go to the "API REST"
107
-
section, selecting the `.env` tab.
108
-
109
-
3. Copy the URL and token information displayed there and paste them in the
110
-
`.env` file under the following variables:
111
-
112
-
```
113
-
# UPSTASH redis for waiting list
114
-
UPSTASH_REDIS_REST_URL="https://•••••••••.upstash.io"
115
-
UPSTASH_REDIS_REST_TOKEN="•••••••••"
116
-
```
117
-
118
-
Replace the ellipsis with the actual URL and token of Redis you obtained from
119
-
UPSTASH.
120
-
121
-
## Setting up Tinybird
122
-
123
-
You will need to create an API token, Go to Auth tokens > Workspace tokens > Add
124
-
a new token > Select your token
125
-
126
-
127
-
```
128
-
# TinyBird
129
-
TINY_BIRD_API_KEY="•••••••••"
130
-
```
131
-
132
-
The [Tinybird CLI](https://www.tinybird.co/docs/cli.html) can be used to push
133
-
the pipes to the Tinybird server.
134
-
135
-
### Datasource
136
-
137
-
We ingest the monitor response into the `ping_response__v5` table. If you want
138
-
to have some dummy data to start with, check out the
139
-
[csv](https://raw.githubusercontent.com/openstatusHQ/openstatus/main/apps/docs/dummy/ping_response__v5.csv)
140
-
file.
141
-
142
-
> Warning: If importing the csv file, make sure to change the column names are
143
-
> identical (e.g. `monitorId` instead of `monitorid`). Otherwise, the pipes will
144
-
> not work.
145
-
146
-
### Pipes
147
-
148
-
The pipes we are using can be found under `@packages/tinybird/pipes`. Pipes are
149
-
used to transform data from one format to another. For example, we are using a
150
-
pipe to transform the data from the database `ping_response` into aggregated
151
-
data.
152
-
153
-
We currently have three pipes:
154
-
155
-
1. `status_timezone__v0`: returns aggregated data from the `ping_response`
156
-
table.
157
-
2. `response_list__v0`: returns the list of responses from the `ping_response`
158
-
table.
159
-
3. `home_stats__v0`: returns the total amount of pings during a timeframe from
160
-
the `ping_response` table.
161
-
162
-
## Setting up Turso (SQLite or Cloud Database)
163
-
164
-
The "TURSO SQLITE" section in the `.env` file allows you to configure Turso
165
-
database, either a local SQLite database or a cloud-based database.
166
-
167
-
### If you want to use a local database (optional):
168
-
169
-
To begin, install sqld with brew. If you don't have brew installed, we recommend
170
-
installing it from [brew.sh](https://brew.sh/) which works on macOS or Linux, or
171
-
WSL if you are using Windows.
172
-
173
-
```bash
174
-
brew tap libsql/sqld
175
-
brew install sqld-beta
176
-
```
177
-
178
-
Next, you can use the following command to start Turso with a SQLite database:
179
-
180
-
```bash
181
-
turso dev --db-file openstatus.db
182
-
```
183
-
184
-
By doing this, you'll be able to work with the local database without modifying
185
-
the `.env` file.
186
-
187
-
### If you want to use a cloud-based database with Turso
188
-
189
-
To use a cloud-based database with Turso, follow these steps:
190
-
191
-
1. Log in to your Turso account at [https://turso.tech/](https://turso.tech/) or
192
-
create a new account if you don't have one yet.
193
-
194
-
2. If this is your first time using Turso, it may prompt you to install the
195
-
client on your machine. Follow the steps provided on their website or refer
196
-
to their documentation
197
-
[https://docs.turso.tech/tutorials/get-started-turso-cli/step-01-installation](https://docs.turso.tech/tutorials/get-started-turso-cli/step-01-installation)
198
-
for client installation.
199
-
200
-
3. Once you have successfully installed the Turso client, open your terminal and
201
-
use the following command to authenticate:
202
-
203
-
```
204
-
turso auth login
205
-
```
206
-
207
-
4. Then, create a new database with the following command:
208
-
209
-
```
210
-
turso db create
211
-
```
212
-
213
-
Wait for a moment until the database is created, and you will be shown
214
-
information about the database, including a connection URL and an authentication
215
-
token.
216
-
217
-
5. Use the following commands to show the required information and create the
218
-
database in the `.env` file:
219
-
220
-
```
221
-
turso db show db-name
222
-
turso db tokens create db-name
223
-
```
224
-
225
-
Replace "db-name" with the name of your database. You should get the generated
226
-
URL and token, which should be placed in the `.env` file as follows (real values
227
-
without censorship):
228
-
229
-
```
230
-
# TURSO SQLITE
231
-
DATABASE_URL=libsql://my-database-example.turso.io
232
-
DATABASE_AUTH_TOKEN=ey••••••••••••••••••••••••••••••••
233
-
```
234
-
235
-
Remember to copy this information in both` app/web/.env` and `packages/db/.env`
236
-
and save the changes to the `.env` file once you have completed all the
237
-
configurations.
238
-
239
-
## **Connect datasource using tinybird-cli**
240
-
241
-
1. Log in to your tinybird account at https://www.tinybird.co/ or create a new
242
-
account if you don't have one yet.
243
-
244
-
2. Once logged in, go to your dashboard and copy the auth token and paste inside
245
-
`.env`
246
-
247
-
> Please make sure you chose the admin token otherwise it may give an error
248
-
> like auth token invalid
249
-
250
-
3. Then download this file
251
-
[ping_response\_\_v5](https://raw.githubusercontent.com/openstatusHQ/openstatus/8d5c997aacd93becff2cf24ea1d08d33274d2c20/apps/docs/dummy/ping_response__v5.csv)
252
-
253
-
4. install the tinybird-cli
254
-
255
-
```
256
-
cd packages/tinybird
257
-
python3 -m venv .venv
258
-
source .venv/bin/activate
259
-
pip install tinybird-cli
260
-
261
-
```
262
-
263
-
5. Create a datasource from this file
264
-
265
-
> Please make sure while importing you edit the table header fields in
266
-
> camelcase .
267
-
268
-
6. Create pipe from the datasource name as a `response_list__v1` and
269
-
`status_timezone__v0`
270
-
271
-
7. Inside `response_list__v0` pipe, create a endpoint by running a following
272
-
query :
273
-
274
-
```
275
-
%
276
-
SELECT id, latency, monitorId, pageId, region, statusCode, timestamp, url, workspaceId, cronTimestamp
277
-
FROM ping_response__v4
278
-
WHERE monitorId = {{ String(monitorId, 'openstatusPing') }}
279
-
{% if defined(region) %}
280
-
AND region = {{ String(region) }}
281
-
{% end %}
282
-
{% if defined(cronTimestamp) %}
283
-
AND cronTimestamp = {{ Int64(cronTimestamp) }}
284
-
{% end %}
285
-
{% if defined(fromDate) %}
286
-
AND cronTimestamp >= {{ Int64(fromDate) }}
287
-
{% end %}
288
-
{% if defined(toDate) %}
289
-
AND cronTimestamp <= {{ Int64(toDate) }}
290
-
{% end %}
291
-
ORDER BY timestamp DESC
292
-
LIMIT {{Int32(limit, 1000)}}
293
-
```
294
-
295
-
8. Inside `status_timezone__v0` pipe , create a endpoint by running a following
296
-
query :
297
-
298
-
```
299
-
VERSION 0
300
-
301
-
NODE group_by_cronTimestamp
302
-
SQL >
303
-
304
-
%
305
-
SELECT
306
-
toDateTime(cronTimestamp / 1000, 'UTC') AS day,
307
-
-- only for debugging purposes
308
-
toTimezone(day, {{ String(timezone, 'Europe/Berlin') }}) as with_timezone,
309
-
toStartOfDay(with_timezone) as start_of_day,
310
-
avg(latency) AS avgLatency,
311
-
count() AS count,
312
-
count(multiIf((statusCode >= 200) AND (statusCode <= 299), 1, NULL)) AS ok
313
-
FROM ping_response__v4
314
-
WHERE
315
-
(day IS NOT NULL)
316
-
AND (day != 0)
317
-
AND monitorId = {{ String(monitorId, '1') }}
318
-
-- By default, we only only query the last 45 days
319
-
AND cronTimestamp >= toUnixTimestamp64Milli(
320
-
toDateTime64(toStartOfDay(date_sub(DAY, 45, now())), 3)
321
-
)
322
-
GROUP BY cronTimestamp, monitorId
323
-
ORDER BY day DESC
324
-
325
-
326
-
327
-
NODE group_by_day
328
-
SQL >
329
-
330
-
%
331
-
SELECT
332
-
start_of_day as day,
333
-
sum(count) as count,
334
-
sum(ok) as ok,
335
-
round(avg(avgLatency)) as avgLatency
336
-
FROM group_by_cronTimestamp
337
-
GROUP BY start_of_day
338
-
ORDER BY start_of_day DESC
339
-
LIMIT {{ Int32(limit, 100) }}
340
-
341
-
342
-
```
343
-
344
-
### Setting up the database
345
-
346
-
We have an example database that you can use to get started. You can run it with
347
-
the following command:
348
-
349
-
```bash
350
-
turso dev --db-file openstatus-dev.db
351
-
```
352
-
353
-
It contains some dummy data that you can use to test the application.
354
-
355
-
356
-
357
-
<Image
358
-
src={Drizzle}
359
-
alt="Drizzle"
360
-
/>
361
-
362
-
363
-
364
-
```bash
365
-
cd packages/db
366
-
pnpm studio
367
-
```
368
-
369
-
## Conclusion
370
-
371
-
Once you have collected all the necessary information, you should save it in the
372
-
`.env` file to ensure proper configuration for your application. Following these
373
-
steps will enable your application to function effectively with the appropriate
374
-
settings for each service.
375
-
376
-
Open this url http://localhost:3000/app/love-openstatus to start using the app.
+32
-9
apps/docs/src/content/docs/getting-started/introduction.mdx
+32
-9
apps/docs/src/content/docs/getting-started/introduction.mdx
···
1
1
---
2
2
title: Getting Started with openstatus
3
-
description: "How to get started with OpenStatus?"
3
+
description: "How to get started with openstatus?"
4
4
topic: docs
5
5
next: 'Start Monitoring'
6
6
---
···
8
8
import { Aside } from '@astrojs/starlight/components';
9
9
10
10
11
-
You can use OpenStatus by either signing up for our **cloud version** or by **self-hosting** the application on your own infrastructure.
11
+
You can use openstatus by either signing up for our **cloud version** or by **self-hosting** the application on your own infrastructure.
12
12
13
13
14
14
## Cloud Version
···
19
19
20
20
## Self-Hosted Version
21
21
22
-
For users who want to host OpenStatus on their own infrastructure, all our code is [open source](https://github.com/openstatushq/openstatus)
22
+
For users who want to host openstatus on their own infrastructure, all our code is [open source](https://github.com/openstatushq/openstatus).
23
+
24
+
We offer a few ways to get started with self-hosting:
25
+
26
+
### With Docker (Recommended)
27
+
28
+
The fastest way to get started for both development and self-hosting is with Docker.
29
+
30
+
```sh
31
+
# 1. Copy environment file
32
+
cp .env.docker.example .env.docker
33
+
34
+
# 2. Start all services
35
+
docker compose up -d
36
+
37
+
# 3. Access the application
38
+
open http://localhost:3002 # Dashboard
39
+
open http://localhost:3003 # Status Pages
40
+
```
23
41
24
-
While we are working on making the self-hosted version easier to deploy, you can start with a community-maintained option like the **Vercel Edge Checker**.
42
+
For a complete guide on using Docker, including database setup and configuration, please see our [DOCKER.md](https://github.com/openstatushq/openstatus/blob/main/DOCKER.md) file.
25
43
26
-
### Vercel Edge Checker
44
+
### With Devbox
27
45
28
-
The Vercel Edge Checker is a lightweight version of OpenStatus that you can deploy to Vercel with a single click. It's a great way to get familiar with self-hosting OpenStatus.
46
+
You can use [Devbox](https://www.jetify.com/devbox/) to easily manage your development environment.
29
47
48
+
1. Install Devbox
49
+
```sh
50
+
curl -fsSL https://get.jetify.com/devbox | bash
51
+
```
52
+
2. Install project dependencies, build and start services
53
+
```sh
54
+
devbox services up
55
+
```
30
56
31
-
<Aside>
32
-
We are actively working to simplify self-hosting and have an open [issue](https://github.com/openstatusHQ/openstatus/issues/322) on GitHub regarding this. Stay tuned!
33
-
</Aside>
+37
-9
apps/docs/src/content/docs/guides/getting-started.mdx
+37
-9
apps/docs/src/content/docs/guides/getting-started.mdx
···
1
1
---
2
-
title: Introduction
3
-
description: Guides to get started with OpenStatus guides
2
+
title: How-to Guides
3
+
description: Problem-solving guides for specific tasks with openstatus
4
4
sidebar:
5
5
label: Introduction
6
6
order: 1
7
7
---
8
8
9
-
Here's some guides for the getting started with OpenStatus.
9
+
## 🛠️ How-to Guides
10
+
11
+
### What you'll find here
12
+
13
+
Our how-to guides are designed to help you:
14
+
- Solve specific problems with step-by-step instructions
15
+
- Implement advanced features and integrations
16
+
- Customize and extend your openstatus setup
10
17
18
+
### Monitoring & Integration
11
19
12
-
- [How to monitor your MCP Server using OpenStatus](/guides/how-to-monitor-mcp-server/)
13
-
- [How to run synthetic tests in your GitHub Actions](/guides/how-to-run-synthetic-test-github-action/)
14
-
- [Export Metrics to your OTLP endpoint](/guides/how-to-export-metrics-to-otlp-endpoint)
15
-
- [How to Add an SVG Status Badge to your GitHub README](/guides/how-to-add-svg-status-badge)
16
-
- [How to use React Status Widget](/guides/how-to-use-react-widget)
17
-
- [How to deploy private location on Cloudflare Containers](/guides/how-to-deploy-probes-cloudflare-containers)
20
+
Extend your monitoring capabilities:
21
+
22
+
- **[Monitor Your MCP Server](/guides/how-to-monitor-mcp-server/)** - Set up monitoring for Model Context Protocol servers
23
+
- **[Export Metrics to OTLP Endpoint](/guides/how-to-export-metrics-to-otlp-endpoint)** - Send monitoring data to your observability platform
24
+
- **[Run Synthetic Tests in GitHub Actions](/guides/how-to-run-synthetic-test-github-action/)** - Automate testing in your CI/CD pipeline
25
+
26
+
### Status Pages & Widgets
27
+
28
+
Share your status with users:
29
+
30
+
- **[Add SVG Status Badge to GitHub README](/guides/how-to-add-svg-status-badge)** - Display real-time status in your repository
31
+
- **[Use React Status Widget](/guides/how-to-use-react-widget)** - Embed live status updates in your React application
32
+
- **[Deploy Status Page on Cloudflare Pages](/guides/how-deploy-status-page-cf-pages)** - Host your status page on Cloudflare's edge network
33
+
34
+
### Infrastructure & Deployment
35
+
36
+
Self-host and customize your setup:
37
+
38
+
- **[Deploy Private Locations on Cloudflare Containers](/guides/how-to-deploy-probes-cloudflare-containers)** - Run monitoring agents in your own infrastructure
39
+
- **[Self-Host openstatus](/guides/self-hosting-openstatus)** - Deploy openstatus on your own servers
40
+
41
+
### Related sections
42
+
43
+
- **[Tutorials](/tutorial/getting-started/)** - If you need step-by-step learning instead
44
+
- **[Explanations](/concept/getting-started/)** - To understand the concepts behind these guides
45
+
- **[Reference](/reference)** - For detailed technical specifications
+13
-13
apps/docs/src/content/docs/guides/how-deploy-status-page-cf-pages.mdx
+13
-13
apps/docs/src/content/docs/guides/how-deploy-status-page-cf-pages.mdx
···
1
1
---
2
2
title: How to deploy your own status page to Cloudflare Pages
3
-
description: Learn how to use OpenStatus monitoring data and deploy your own Status Page to cloudflare pages.
3
+
description: Learn how to use openstatus monitoring data and deploy your own Status Page to cloudflare pages.
4
4
sidebar:
5
5
label: Host your status page on Cloudflare Pages
6
6
---
···
9
9
10
10
## Introduction
11
11
12
-
At OpenStatus, we believe that monitoring your endpoints should be easy and accessible to everyone.
12
+
At openstatus, we believe that monitoring your endpoints should be easy and accessible to everyone.
13
13
We also believe that having a status page is essential for your users to know the status of your services.
14
-
We also think that manually updating your status page is a waste of time. The best way to update your status page is to automate it. That's why we built OpenStatus.
14
+
We also think that manually updating your status page is a waste of time. The best way to update your status page is to automate it. That's why we built openstatus.
15
15
16
-
In this guide, we will show you how to deploy your own status page to Cloudflare Pages using OpenStatus monitoring data.
16
+
In this guide, we will show you how to deploy your own status page to Cloudflare Pages using openstatus monitoring data.
17
17
18
18
For the Status Page, we will use [Astro](https://astro.build/) a new JavaScript web framework, that allows you to build faster websites with less JavaScript.
19
19
···
32
32
To follow this guide, you need:
33
33
34
34
- A Cloudflare Account.
35
-
- An [OpenStatus](https://www.openstatus.dev) Account.
35
+
- An [openstatus](https://www.openstatus.dev) Account.
36
36
37
37
## Start monitoring your services
38
38
39
-
To get your monitoring data, you need to create a monitor on OpenStatus.
39
+
To get your monitoring data, you need to create a monitor on openstatus.
40
40
We will monitor the status of your endpoint and get the data to display on your status page.
41
41
42
42
43
43
### How to create a monitor
44
44
45
45
To create a monitor, follow these steps:
46
-
1. Go to the OpenStatus dashboard.
46
+
1. Go to the openstatus dashboard.
47
47
2. Click on the `Monitors` tab.
48
48
3. Click on the `Create Monitor` button.
49
49
4. Fill in the form with your endpoint details.
50
50
5. Click on the `Create Monitor` button.
51
51
52
52
53
-
### Get your OpenStatus API key
53
+
### Get your openstatus API key
54
54
55
55
To get your API key, follow these steps:
56
56
57
-
1. Go to the OpenStatus dashboard.
57
+
1. Go to the openstatus dashboard.
58
58
2. Click on the `Settings` tab.
59
59
3. Click on the `API Token` tab.
60
60
4. Click on the `Create API Key` button.
···
62
62
63
63
## Deploy your own status page
64
64
65
-
With OpenStatus monitoring data, you can bring your status page to life. You can really make it your own.
65
+
With openstatus monitoring data, you can bring your status page to life. You can really make it your own.
66
66
We are going to deploy a simple status page that shows the status of your endpoint.
67
67
68
68
For this guide we are going to use our [Astro Status Page](https://github.com/openstatusHQ/astro-status-page) template.
69
69
70
70
### Customize the Astro Status Page
71
71
72
-
In the `index.astro` we are fetching the monitor data from OpenStatus and displaying it on the page.
72
+
In the `index.astro` we are fetching the monitor data from openstatus and displaying it on the page.
73
73
74
74
```ts
75
75
const response = await fetch("https://api.openstatus.dev/v1/monitor", {
···
99
99
100
100
Select your site and click on the `Settings` tab.
101
101
102
-
You can add your OpenStatus API key as an environment variable.
102
+
You can add your openstatus API key as an environment variable.
103
103
104
104
```env
105
105
API_KEY=your-api-key
···
111
111
npm run pages:deploy
112
112
```
113
113
114
-
Your Status Page is now live on Cloudflare Pages. 🎉
114
+
Your Status Page is now live on Cloudflare Pages. 🎉
+8
-8
apps/docs/src/content/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx
+8
-8
apps/docs/src/content/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx
···
1
1
---
2
2
title: How to deploy the openstatus probe to Cloudflare Containers
3
-
description: Learn how to use OpenStatus monitoring data and deploy your own Status Page to cloudflare pages.
3
+
description: Learn how to use openstatus monitoring data and deploy your own Status Page to cloudflare pages.
4
4
sidebar:
5
5
label: Deploy private probes on Cloudflare Containers
6
6
---
···
9
9
import os from '../../../assets/guides/how-to-deploy-probes-cf-containters/private-location.jpg';
10
10
11
11
12
-
In this guide we will show you how to deploy the OpenStatus probe to Cloudflare Containers.
12
+
In this guide we will show you how to deploy the openstatus probe to Cloudflare Containers.
13
13
14
14
Cloudflare Containers is a platform that allows you to run serverless containers in the Cloudflare network.
15
15
···
23
23
24
24
25
25
26
-
### Create a private location on OpenStatus
26
+
### Create a private location on openstatus
27
27
28
-
1. Go to the OpenStatus dashboard.
28
+
1. Go to the openstatus dashboard.
29
29
2. Click on the `Private locations` in the sidebar.
30
30
3. Click on the `Create Private Location` button.
31
31
4. Give it a human readable name.
···
95
95
},
96
96
```
97
97
98
-
9. Add you OpenStatus API secret
98
+
9. Add you openstatus API secret
99
99
100
100
```bash
101
101
pnpm wrangler secret put OPENSTATUS_KEY
···
118
118
119
119
<Image
120
120
src={log}
121
-
alt="OpenStatus Private Location on Cloudflare Containers"
122
-
caption="Cloudflare Workers Logs showing OpenStatus Private Location running"
121
+
alt="openstatus Private Location on Cloudflare Containers"
122
+
caption="Cloudflare Workers Logs showing openstatus Private Location running"
123
123
/>
124
124
125
125
<Image
126
126
src={os}
127
-
alt="OpenStatus Private Location on Cloudflare Containers"
127
+
alt="openstatus Private Location on Cloudflare Containers"
128
128
/>
+91
-50
apps/docs/src/content/docs/guides/how-to-monitor-mcp-server.mdx
+91
-50
apps/docs/src/content/docs/guides/how-to-monitor-mcp-server.mdx
···
1
1
---
2
-
title: How to monitor your Model Context Provider (MCP) server?
3
-
description: Learn how to monitor your MCP server with openstatus.
2
+
title: How to Monitor Your Model Context Provider (MCP) Server
3
+
description: Learn how to monitor your MCP server with openstatus using JSON-RPC ping checks
4
4
sidebar:
5
5
label: Monitor your MCP Server
6
6
---
7
-
In this guide, we will show you how to monitor your remote MCP server using OpenStatus. We will use the Hugging Face MCP server for this article, but you can apply the same principles to any MCP server. You can find the code for this guide on [GitHub](https://github.com/openstatusHQ/template/tree/a69eac06e9d3d8579768dad803304e456f56ec33/mcp-server).
8
7
9
-
**Prerequisites**
8
+
## Problem: Ensuring Your MCP Server is Always Responsive
10
9
11
-
- An OpenStatus account and CLI
12
-
- An MCP server
10
+
Running a Model Context Provider (MCP) server is critical for your AI applications, but traditional HTTP monitoring often falls short. MCP servers communicate using the JSON-RPC 2.0 protocol, requiring specific request/response patterns that standard health checks don't cover. How can you confidently ensure your MCP server is healthy and responsive at all times, without custom scripts or complex setups?
13
11
14
-
## Model Context Provider (MCP)
12
+
## Solution: JSON-RPC Ping Monitoring with openstatus
15
13
16
-
A Model Context Provider is a component that supplies additional context, data, or capabilities to AI models during runtime through the Model Context Protocol (MCP). It acts as a bridge, allowing AI models to access external resources such as databases, APIs, file systems, or other services not included in their original training data.
14
+
openstatus offers a robust solution for monitoring your MCP servers. By sending precise JSON-RPC `ping` requests to your endpoint from multiple global locations, openstatus verifies not only network reachability but also the correct functioning of your server's JSON-RPC interface. This guide will walk you through setting up comprehensive monitoring for any MCP server using the openstatus CLI.
17
15
18
-
### What is an MCP Server?
16
+
## Prerequisites
19
17
20
-
The server component of the MCP protocol hosts and manages external resources, tools, or data sources that AI models can access. It handles incoming requests from MCP clients, processes them according to the protocol specifications, and returns the requested information or executes the specified actions. The MCP server serves as the backend provider, exposing capabilities like database queries, file operations, or API calls in a standardized format for AI models to interact with.
18
+
Before you begin, ensure you have:
21
19
22
-
The protocol must adhere to the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification).
20
+
- An [openstatus account](https://www.openstatus.dev/app/login).
21
+
- The [openstatus CLI installed](/tutorial/get-started-with-openstatus-cli). (If you haven't installed it yet, follow this guide first).
22
+
- An MCP server with a publicly accessible endpoint.
23
+
- A basic understanding of the [JSON-RPC 2.0 protocol](https://www.jsonrpc.org/specification).
23
24
24
-
### JSON-RPC Protocol
25
+
## Background: Understanding MCP for Monitoring
25
26
26
-
JSON-RPC is a remote procedure call protocol that uses JSON as its data format. It is designed to be simple and easy to implement while providing a robust and flexible way to communicate between clients and servers. The JSON-RPC protocol is transport-independent, but for MCP servers, it uses HTTP/HTTPS, making it easy to monitor with OpenStatus.
27
+
A Model Context Provider (MCP) is a crucial component that extends AI models with external context, data, or capabilities via the **Model Context Protocol (MCP)**. Essentially, it acts as a bridge, allowing AI models to interact with resources like databases, APIs, or file systems that aren't part of their core training.
27
28
28
-
### Ping Utility
29
+
### The MCP Server and JSON-RPC 2.0
29
30
30
-
The official [MCP documentation](https://modelcontextprotocol.io/docs/concepts/architecture#debugging-and-monitoring) recommends implementing a health check for your MCP server. The protocol includes a mechanism to verify that the server is still responsive: the ping utility. The ping feature operates using a basic request/response mechanism.
31
+
The MCP server is the backend component that hosts these external resources. It processes incoming requests from MCP clients, executes specified actions, and returns information according to the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification). JSON-RPC is a lightweight remote procedure call protocol using JSON for data exchange. While transport-independent, MCP servers typically use HTTP/HTTPS, making them readily monitorable by openstatus.
31
32
32
-
## Create Your OpenStatus Monitor
33
+
### The Ping Utility: Health Check Standard
33
34
34
-
OpenStatus allows you to monitor your MCP server by sending a ping request to your MCP server's endpoint on a regular basis from multiple locations around the world. Making it easy to monitor your remote MCP server's health and performance.
35
+
For robust monitoring, the official [MCP documentation](https://modelcontextprotocol.io/docs/concepts/architecture#debugging-and-monitoring) recommends implementing a health check using the **ping utility**. This simple request/response mechanism verifies the server's responsiveness and is the foundation for our openstatus monitor.
35
36
36
-
### YAML Configuration
37
+
## Create Your openstatus Monitor: YAML Configuration
37
38
38
-
The [OpenStatus CLI](/tutorial/get-started-with-openstatus-cli) allows you to create monitor defined in a YAML configuration file. This is perfect solution if want to manage your monitors via GitOps.
39
+
openstatus allows you to define and manage your monitors using YAML configuration files, a perfect solution for GitOps workflows. This approach ensures your monitoring setup is version-controlled, auditable, and easily deployable via the openstatus CLI.
39
40
40
-
Here's an example of a monitor configuration for Hugging Face MCP server:
41
+
Here's an example of a monitor configuration for a Hugging Face MCP server, which you can adapt for your own MCP endpoint:
41
42
42
-
```YAML
43
+
```yaml
43
44
# yaml-language-server: $schema=https://www.openstatus.dev/schema.json
44
45
45
46
mcp-server:
···
60
61
"method": "ping"
61
62
}
62
63
headers:
63
-
User-Agent: OpenStatus
64
+
User-Agent: openstatus
64
65
Accept: application/json, text/event-stream
65
66
Content-Type: application/json
66
67
assertions:
···
72
73
target: '{"result":{},"jsonrpc":"2.0","id":"openstatus"}'
73
74
```
74
75
75
-
### What Does This Monitor Do?
76
+
### Understanding the Configuration
76
77
77
-
We send an HTTP POST request to the MCP server. The request body contains a JSON-RPC request with the method "ping".
78
+
Let's break down the key fields in this YAML configuration:
78
79
79
-
```json
80
-
{
81
-
"jsonrpc": "2.0",
82
-
"id": "openstatus",
83
-
"method": "ping"
84
-
}
85
-
```
80
+
- `name`: A human-readable name for your monitor (e.g., "HF MCP Server").
81
+
- `description`: A brief explanation of what this monitor checks.
82
+
- `frequency`: How often openstatus will run the check. Common values include `30s`, `1m`, `5m`, `10m`, `30m`, `1h`. Setting a sensible frequency balances timely alerts with resource usage.
83
+
- `active`: Set to `true` to enable the monitor, `false` to disable it.
84
+
- `regions`: An array of geographic regions from which openstatus will perform the checks (e.g., `["iad", "ams", "lax"]` for North America, Europe, and West US). Monitoring from multiple regions helps detect localized issues.
85
+
- `retry`: The number of times openstatus will retry a failed check before marking it as genuinely down. This helps prevent false positives due to transient network issues.
86
+
- `kind`: Specifies the type of monitor. For MCP servers using HTTP/HTTPS, this will be `http`.
87
+
- `request`:
88
+
- `url`: The full URL of your MCP server's JSON-RPC endpoint.
89
+
- `method`: The HTTP method, which should be `POST` for JSON-RPC requests.
90
+
- `body`: The JSON-RPC `ping` request payload. The `"method": "ping"` is crucial for triggering the health check on your MCP server.
91
+
```json
92
+
{
93
+
"jsonrpc": "2.0",
94
+
"id": "openstatus",
95
+
"method": "ping"
96
+
}
97
+
```
98
+
- `headers`: Standard HTTP headers for JSON-RPC communication.
99
+
- `assertions`: Rules to validate the response from your MCP server. These are critical for determining if the server is healthy.
100
+
- **Status Code Check**: `statusCode` assertion ensures the HTTP response is `200` (OK).
101
+
```yaml
102
+
- kind: statusCode
103
+
compare: eq
104
+
target: 200
105
+
```
106
+
- **Response Body Check**: `textBody` assertion verifies that the response payload matches the expected JSON-RPC `ping` result. The `target` value must precisely match the successful `ping` response from your MCP server.
107
+
```yaml
108
+
- kind: textBody
109
+
compare: eq
110
+
target: '{"result":{},"jsonrpc":"2.0","id":"openstatus"}'
111
+
```
86
112
87
-
We set our headers to accept `application/json` and `text/event-stream`. We also include assertions to verify the response.
113
+
### Testing Your MCP Server (Optional)
88
114
89
-
First, we check that the status code is 200.
115
+
Before deploying your openstatus monitor, it's a good practice to manually test your MCP server's `ping` endpoint using `curl` to ensure it responds as expected. This helps in debugging and confirming the `target` value for your `textBody` assertion.
90
116
91
-
```YAML
92
-
- kind: statusCode
93
-
compare: eq
94
-
target: 200
117
+
```bash
118
+
curl -X POST \\
119
+
-H "Content-Type: application/json" \\
120
+
-d '{"jsonrpc": "2.0", "id": "openstatus", "method": "ping"}' \\
121
+
https://hf.co/mcp # Replace with your MCP server URL
95
122
```
96
123
97
-
Next, we verify that the response body is correct.
98
-
99
-
```YAML
100
-
- kind: textBody
101
-
compare: eq
102
-
target: '{"result":{},"jsonrpc":"2.0","id":"openstatus"}'
103
-
```
124
+
This command should return a JSON response similar to `{"result":{},"jsonrpc":"2.0","id":"openstatus"}` if your MCP server is healthy and correctly implements the `ping` utility.
104
125
105
-
### Using OpenStatus CLI to Create Your Monitor
126
+
### Using openstatus CLI to Create Your Monitor
106
127
107
-
To create your monitor, use the OpenStatus CLI.
128
+
Once your `openstatus.yaml` file is ready, create your monitor using the openstatus CLI:
108
129
109
130
```bash
110
131
openstatus create openstatus.yaml
111
132
```
112
133
113
-
## Conclusion
134
+
This command will upload your monitor configuration to openstatus, and monitoring will begin according to the specified `frequency` and `regions`.
135
+
136
+
## Conclusion: Comprehensive MCP Server Monitoring Achieved
137
+
138
+
This guide has equipped you with the knowledge to effectively monitor your MCP server using openstatus. By leveraging YAML configuration and the openstatus CLI, you can ensure your critical AI infrastructure remains healthy and responsive.
139
+
140
+
## What You've Accomplished
141
+
142
+
- ✅ Successfully configured a JSON-RPC based monitor for your MCP server.
143
+
- ✅ Implemented precise assertions to validate `ping` responses.
144
+
- ✅ Set up global monitoring to detect localized or widespread issues.
145
+
- ✅ Automated monitor deployment using a version-controlled YAML configuration.
146
+
147
+
## Next Steps
148
+
149
+
Now that your MCP server is under robust monitoring, consider further enhancing your setup:
114
150
115
-
This guide has shown you how to create a monitor for your MCP server using the OpenStatus CLI. You can view the monitor in the OpenStatus dashboard.
151
+
- **[Set up Alerting](/monitoring/customization/notification)**: Configure notifications to be immediately informed of any MCP server downtime or performance degradation.
152
+
- **[Export Metrics to OTLP](/guides/how-to-export-metrics-to-otlp-endpoint)**: Integrate your MCP monitoring data with your existing observability platform for centralized analytics.
153
+
- **[Run Synthetic Tests in GitHub Actions](/guides/how-to-run-synthetic-test-github-action/)**: Incorporate these synthetic checks into your CI/CD pipeline for pre-deployment validation.
116
154
117
-
For example, here is our monitor for the HF MCP server:
155
+
## Related Resources
118
156
119
-
[https://www.openstatus.dev/public/monitors/5961](https://www.openstatus.dev/public/monitors/5961)
157
+
- **[JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)**: Deep dive into the JSON-RPC protocol.
158
+
- **[MCP Official Documentation](https://modelcontextprotocol.io/docs/concepts/architecture#debugging-and-monitoring)**: Official insights into MCP health checks.
159
+
- **[HTTP Monitor Reference](/reference/http-monitor)**: Comprehensive API reference for HTTP monitors.
160
+
- **[CLI Reference](/reference/cli-reference)**: Full documentation for the openstatus CLI.
+132
-25
apps/docs/src/content/docs/guides/how-to-run-synthetic-test-github-action.mdx
+132
-25
apps/docs/src/content/docs/guides/how-to-run-synthetic-test-github-action.mdx
···
1
1
---
2
-
title: How to run a synthetic test in a GitHub Action
3
-
description: Learn how to run a synthetic test in a GitHub Action using OpenStatus.
2
+
title: How to Run Synthetic Tests in GitHub Actions
3
+
description: Integrate openstatus synthetic monitoring into your CI/CD pipeline
4
4
sidebar:
5
-
label: GitHub Action for Synthetics Tests
5
+
label: GitHub Action for Synthetics
6
6
---
7
7
8
-
In this guide, we will show you how to run a synthetic test in a GitHub Action using OpenStatus.
8
+
## Problem
9
9
10
-
### Requirements
10
+
You want to validate that your application's critical endpoints are working before deploying to production. Running synthetic tests in your CI/CD pipeline catches issues early and prevents broken deployments.
11
11
12
-
- An [OpenStatus](https://www.openstatus.dev) Account .
13
-
- A GitHub Repository.
12
+
## Solution
14
13
15
-
### Create a configuration file
14
+
openstatus provides a GitHub Action that runs your configured monitors as part of your CI/CD workflow. This guide shows you how to set it up.
16
15
17
-
First, you need to create a configuration file for your synthetic test.
16
+
## Prerequisites
18
17
18
+
- An [openstatus](https://www.openstatus.dev) account
19
+
- A GitHub repository
20
+
- At least one monitor configured in openstatus
21
+
- Admin access to your GitHub repository (for secrets)
22
+
23
+
## Step-by-step guide
24
+
25
+
### 1. Create a configuration file
26
+
27
+
Create a file named `openstatus.config.yaml` in your repository root:
19
28
20
29
```yaml
21
30
tests:
···
23
32
- 1
24
33
- 2
25
34
```
26
-
The ids are the ids of the monitors you want to run. You can find the ids in the URL of the monitor page.
27
35
36
+
**Finding monitor IDs:**
37
+
1. Go to your openstatus dashboard
38
+
2. Click on a monitor
39
+
3. The ID is in the URL: `https://www.openstatus.dev/app/[workspace]/monitors/[ID]`
28
40
29
-
### Get your OpenStatus API Key
41
+
**Tip:** Start with your most critical monitors and expand from there.
30
42
31
-
You can find your API key in the settings page of your OpenStatus account.
32
-
Go to the settings page and copy your API key.
43
+
### 2. Get your openstatus API key
33
44
45
+
1. Go to your openstatus workspace settings
46
+
2. Navigate to the API section
47
+
3. Create a new API key or copy an existing one
48
+
4. Store it securely - you'll need it for the next step
34
49
50
+
### 3. Add your API key to GitHub Secrets
35
51
36
-
### Add your API Key to GitHub Secrets
37
-
38
-
Go to the settings of your repository and add a new secret with the name `OPENSTATUS_API_KEY` and the value of your OpenStatus API key.
52
+
Secure your API key as a GitHub secret:
39
53
54
+
1. Go to your GitHub repository
55
+
2. Click **Settings** → **Secrets and variables** → **Actions**
56
+
3. Click **New repository secret**
57
+
4. Name: `OPENSTATUS_API_KEY`
58
+
5. Value: Your openstatus API key
59
+
6. Click **Add secret**
40
60
41
-
### Create a GitHub Action
61
+
### 4. Create the GitHub Action workflow
42
62
43
-
Create a new file in your repository under `.github/workflows` with the following content:
63
+
Create `.github/workflows/openstatus.yml`:
44
64
45
65
```yaml
46
-
name: Run OpenStatus Synthetics CI
66
+
name: Run openstatus Synthetics CI
47
67
48
68
on:
49
-
workflow_dispatch:
69
+
workflow_dispatch: # Manual trigger
50
70
push:
51
-
branches: [ main ]
71
+
branches: [ main ] # Trigger on push to main
72
+
pull_request: # Run on PRs (optional)
52
73
53
74
jobs:
54
75
synthetic_ci:
55
76
runs-on: ubuntu-latest
56
-
name: Run OpenStatus Synthetics CI
77
+
name: Run openstatus Synthetics CI
57
78
steps:
58
79
- name: Checkout
59
80
uses: actions/checkout@v4
60
-
- name: Run OpenStatus Synthetics CI
81
+
82
+
- name: Run openstatus Synthetics CI
61
83
uses: openstatushq/openstatus-github-action@v1
62
84
with:
63
85
api_key: ${{ secrets.OPENSTATUS_API_KEY }}
64
86
```
65
87
66
-
### Run the GitHub Action
88
+
### 5. Commit and push
89
+
90
+
```bash
91
+
git add openstatus.config.yaml .github/workflows/openstatus.yml
92
+
git commit -m "Add openstatus synthetic tests to CI"
93
+
git push origin main
94
+
```
95
+
96
+
The GitHub Action will run automatically on the next push to `main`.
97
+
98
+
## What you've accomplished
99
+
100
+
Great work! You've successfully:
101
+
- ✅ Integrated openstatus into your CI/CD pipeline
102
+
- ✅ Automated synthetic testing on every deployment
103
+
- ✅ Added a safety check before production releases
104
+
- ✅ Set up continuous validation of critical endpoints
105
+
106
+
## Customization options
107
+
108
+
### Run on different branches
109
+
110
+
```yaml
111
+
on:
112
+
push:
113
+
branches: [ main, staging, develop ]
114
+
```
115
+
116
+
### Run on pull requests
117
+
118
+
```yaml
119
+
on:
120
+
pull_request:
121
+
types: [opened, synchronize, reopened]
122
+
```
123
+
124
+
### Run on a schedule
125
+
126
+
```yaml
127
+
on:
128
+
schedule:
129
+
- cron: '0 */4 * * *' # Every 4 hours
130
+
```
131
+
132
+
### Multiple configuration files
67
133
68
-
On every push to the main branch, the GitHub Action will run the synthetic tests you have configured in the configuration file.
134
+
```yaml
135
+
- name: Run openstatus Synthetics CI
136
+
uses: openstatushq/openstatus-github-action@v1
137
+
with:
138
+
api_key: ${{ secrets.OPENSTATUS_API_KEY }}
139
+
config_file: .openstatus/production.yaml
140
+
```
141
+
142
+
## Best practices
143
+
144
+
1. **Start small**: Begin with 2-3 critical monitors
145
+
2. **Fail fast**: Run synthetic tests early in your pipeline
146
+
3. **Monitor the monitors**: Track your synthetic test success rate
147
+
4. **Environment-specific**: Use different monitors for staging vs production
148
+
5. **Document failures**: Investigate and document any CI failures
149
+
150
+
## Troubleshooting
151
+
152
+
**Action fails with authentication error:**
153
+
- Verify `OPENSTATUS_API_KEY` secret is set correctly
154
+
- Check that your API key hasn't expired
155
+
156
+
**Monitors not found:**
157
+
- Confirm monitor IDs are correct in `openstatus.config.yaml`
158
+
- Ensure monitors are active in your openstatus dashboard
159
+
160
+
**Tests timing out:**
161
+
- Check that your endpoints are accessible from GitHub's runners
162
+
- Consider increasing timeouts in monitor configuration
163
+
164
+
## Next steps
165
+
166
+
- **[Monitor Your MCP Server](/guides/how-to-monitor-mcp-server/)** - Advanced monitoring examples
167
+
- **[Monitoring as Code](/concept/uptime-monitoring-as-code)** - Manage monitors with YAML
168
+
- **[CLI Reference](/reference/cli-reference)** - Automate monitor management
169
+
- **[Export Metrics](/guides/how-to-export-metrics-to-otlp-endpoint)** - Send data to your observability platform
170
+
171
+
## Related resources
172
+
173
+
- **[GitHub Action on Marketplace](https://github.com/marketplace/actions/openstatus-synthetics-ci)** - Official action
174
+
- **[Example Repository](https://github.com/openstatusHQ/github-action-example)** - Working examples
175
+
- **[Join Discord](https://www.openstatus.dev/discord)** - Get help from the community
+1
-1
apps/docs/src/content/docs/guides/how-to-use-react-widget.mdx
+1
-1
apps/docs/src/content/docs/guides/how-to-use-react-widget.mdx
+144
-66
apps/docs/src/content/docs/guides/self-hosting-openstatus.mdx
+144
-66
apps/docs/src/content/docs/guides/self-hosting-openstatus.mdx
···
1
1
---
2
-
title: How to self host openstatus
3
-
description: Learn how to self host openstatus in your own infra.
2
+
title: How to Self-Host openstatus
3
+
description: Complete guide to deploying openstatus on your own infrastructure
4
4
---
5
+
5
6
import { Image } from 'astro:assets';
6
7
7
8
import localOpenstatus from '../../../assets/guides/self-hosting-openstatus/local-openstatus.png';
8
9
10
+
## Problem
9
11
10
-
If you want to self host openstatus, we provide a [docker-compose](https://github.com/openstatusHQ/openstatus/blob/2aa970b7fc2afaca5e3ec584beda69c1f69ca34d/docker-compose.yaml) file to get you started quickly.
12
+
You want to run openstatus on your own infrastructure instead of using the hosted service. This gives you full control over your data, customization options, and the ability to monitor internal services not accessible from the public internet.
11
13
14
+
## Solution
15
+
16
+
openstatus provides a Docker Compose setup that makes self-hosting straightforward. This guide walks you through deploying all necessary services and configuring your self-hosted instance.
17
+
18
+
## Prerequisites
19
+
20
+
- Docker and Docker Compose installed
21
+
- Basic understanding of Docker and containerization
22
+
- Command line experience
23
+
- Git installed
24
+
- Node.js and pnpm (for database migrations)
12
25
13
26
## Known limitations
14
27
15
-
- It only works with private locations. You have to deploy our probes to the cloud provider of your choice.
28
+
Self-hosting openstatus currently has these constraints:
16
29
17
-
## Get started
30
+
- It only works with private locations. You have to deploy our probes to the cloud provider of your choice.
18
31
19
-
1. Clone the repository
32
+
## Step-by-step guide
20
33
21
-
```bash
22
-
git clone
23
-
```
34
+
This guide is divided into three parts: launching the services, setting up the database and analytics, and configuring the application through the UI.
24
35
25
-
2. Copy the `.env.example` file to `.env` and modify the environment variables as needed.
36
+
### Part 1: Initial Setup and Service Launch
26
37
27
-
```bash
28
-
cp .env.docker.example .env.docker
29
-
```
38
+
1. **Clone the Repository**
30
39
31
-
3. Build the containers
32
-
```
33
-
export DOCKER_BUILDKIT=1
34
-
docker compose up -d
35
-
```
40
+
Get the latest version of openstatus:
41
+
```bash
42
+
git clone https://github.com/openstatushq/openstatus
43
+
cd openstatus
44
+
```
36
45
37
-
4. Migrate the database
46
+
2. **Configure Your Environment**
38
47
39
-
```bash
40
-
cd packages/db
41
-
pnpm migrate
42
-
```
48
+
Copy the example environment file. This file will hold all your configuration variables.
49
+
```bash
50
+
cp .env.docker.example .env.docker
51
+
```
52
+
Open `.env.docker` in a text editor. At a minimum, you **must** set a value for `AUTH_SECRET` for authentication to work. For a complete setup, review the file for other variables like OAuth providers or email services.
43
53
44
-
5. Create Tinybird datasources, pipes and endpoints
54
+
3. **Build and Start Services**
45
55
46
-
```bash
47
-
cd packages/tinybird
48
-
tb --local deploy
49
-
```
56
+
Use Docker Compose to build and run all openstatus services in the background.
57
+
```bash
58
+
export DOCKER_BUILDKIT=1
59
+
docker compose up -d
60
+
```
61
+
You can check the status of the services with `docker compose ps`. It might take a few minutes for all services to be healthy.
50
62
51
-
7. Access Tinybird local UI and get your TOKEN
63
+
### Part 2: Database and Analytics Setup
52
64
53
-
```bash
54
-
tb --local open
55
-
```
65
+
4. **Run Database Migrations**
56
66
57
-
8. Update the `.env.docker` file with your Tinybird TOKEN
67
+
The database container starts with an empty database. You must run migrations to set up the required schema.
68
+
```bash
69
+
# Make sure you are in the root of the openstatus project
70
+
cd packages/db
71
+
pnpm install
72
+
pnpm migrate
73
+
cd ../.. # Return to the project root
74
+
```
58
75
59
-
9. Connect to your OpenStatus instance and create a new workspace.
76
+
5. **Deploy Local Tinybird Analytics**
60
77
61
-
10. Update your newly created workspace with the following limits:
78
+
Tinybird is used for analytics. Deploy the local datasources, pipes, and endpoints.
79
+
```bash
80
+
# Make sure you are in the root of the openstatus project
81
+
cd packages/tinybird
82
+
pnpm install
83
+
tb --local deploy
84
+
cd ../.. # Return to the project root
85
+
```
62
86
63
-
```json
64
-
{
65
-
"monitors": 100,
66
-
"periodicity": ["30s", "1m", "5m", "10m", "30m", "1h"],
67
-
"multi-region": true,
68
-
"data-retention": "24 months",
69
-
"status-pages": 20,
70
-
"maintenance": true,
71
-
"status-subscribers": true,
72
-
"custom-domain": true,
73
-
"password-protection": true,
74
-
"white-label": true,
75
-
"notifications": true,
76
-
"sms": true,
77
-
"pagerduty": true,
78
-
"notification-channels": 50,
79
-
"members": "Unlimited",
80
-
"audit-log": true,
81
-
"private-locations": true
82
-
}
83
-
```
87
+
6. **Configure Tinybird API Key**
88
+
89
+
You need to get your local Tinybird admin token and add it to your environment file.
90
+
```bash
91
+
cd packages/tinybird
92
+
tb --local open # This opens the Tinybird UI in your browser
93
+
```
94
+
In the Tinybird UI, find and copy your admin token. Then, add it to your `.env.docker` file in the root of the project:
95
+
```env
96
+
TINY_BIRD_API_KEY="your-tinybird-admin-token"
97
+
```
98
+
After adding the token, restart your services for the changes to take effect:
99
+
```bash
100
+
# Make sure you are in the root of the openstatus project
101
+
docker compose restart
102
+
```
103
+
104
+
### Part 3: Application Configuration
105
+
106
+
Now that the services are running, you can access the dashboard and perform the final setup steps.
107
+
108
+
- **Dashboard:** `http://localhost:3002`
109
+
- **Status Pages:** `http://localhost:3003`
110
+
111
+
7. **Create a Workspace and Set Limits**
112
+
113
+
- Navigate to the dashboard at `http://localhost:3002`.
114
+
- Sign up and create a new workspace.
115
+
- Because this is a self-hosted instance, you need to manually set the feature limits for your workspace directly in the database.
84
116
85
-
11. Create a new private location in the dashboard.
117
+
The following command updates the limits for the workspace with `id = 1`. If your workspace has a different ID, change the `WHERE id = 1` part of the command.
118
+
```bash
119
+
curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \
120
+
-d '{"statements":["UPDATE workspace SET limits = '\''{\\"monitors\\":100,\\"periodicity\\":[\\"30s\\",\\"1m\\",\\"5m\\",\\"10m\\",\\"30m\\",\\"1h\\"],\\"multi-region\\":true,\\"data-retention\\":\\"24 months\\",\\"status-pages\\":20,\\"maintenance\\":true,\\"status-subscribers\\":true,\\"custom-domain\\":true,\\"password-protection\\":true,\\"white-label\\":true,\\"notifications\\":true,\\"sms\\":true,\\"pagerduty\\":true,\\"notification-channels\\":50,\\"members\\":\\"Unlimited\\",\\"audit-log\\":true,\\"private-locations\\":true}'\'' WHERE id = 1"]}'
121
+
```
122
+
You can find your workspace ID by inspecting the database with a command like `curl -X POST http://localhost:8080/ -H "Content-Type: application/json" -d '{"statements":["SELECT id, name FROM workspace"]}'`.
86
123
87
-
12. Deploy the private location to your cloud provider of choice with your location api key `OPENSTATUS_KEY`, and `OPENSTATUS_INGEST_URL` .
124
+
8. **Deploy a Private Location**
125
+
126
+
The self-hosted version relies on private locations to perform checks.
127
+
- In the dashboard, navigate to **Settings -> Private Locations** and create a new one.
128
+
- Copy the generated `OPENSTATUS_KEY`.
129
+
- Deploy the private location probe to your infrastructure using the Docker image `ghcr.io/openstatushq/private-location:latest`.
130
+
- When deploying, you must provide two environment variables to the container:
131
+
- `OPENSTATUS_KEY`: The key you just copied.
132
+
- `OPENSTATUS_INGEST_URL`: The URL of your self-hosted server's API endpoint (e.g., `http://<your-server-ip-or-domain>:3001`).
133
+
- For a detailed guide on deploying a private location, see **[Deploy Private Locations on Cloudflare Containers](/guides/how-to-deploy-probes-cloudflare-containers)**.
88
134
89
-
The docker image of the private location is `ghcr.io/openstatushq/private-location:latest`
135
+
9. **Create Monitors**
90
136
91
-
13. Create monitors and start monitoring your services!
137
+
You're all set! You can now create monitors in the dashboard. They will be checked by the private location you deployed.
92
138
93
139
94
140
<Image
95
141
src={localOpenstatus}
96
-
alt="Openstatus running locally"
142
+
alt="openstatus running locally with self-hosted services"
97
143
/>
98
144
99
145
100
-
## Our services Services
146
+
## Service architecture
147
+
148
+
openstatus consists of multiple services running together:
101
149
102
150
| Service | Port | Purpose |
103
151
|---------|------|---------|
104
-
| workflows | 3000 | Background jobs |
152
+
| workflows | 3000 | Background jobs and scheduled tasks |
105
153
| server | 3001 | API backend (tRPC) |
106
-
| dashboard | 3002 | Admin interface |
154
+
| dashboard | 3002 | Admin interface for configuration |
107
155
| status-page | 3003 | Public status pages |
108
-
| private-location | 8081 | Monitoring agent |
156
+
| private-location | 8081 | Monitoring agent for checks |
109
157
| libsql | 8080 | Database (HTTP) |
110
158
| libsql | 5001 | Database (gRPC) |
111
-
| tinybird-local | 7181 | Analytics |
159
+
| tinybird-local | 7181 | Analytics and metrics |
160
+
161
+
## What you've accomplished
162
+
163
+
Congratulations! You've successfully:
164
+
- ✅ Deployed openstatus on your own infrastructure
165
+
- ✅ Configured all required services
166
+
- ✅ Set up a private location for monitoring
167
+
- ✅ Created your first self-hosted monitor
168
+
169
+
## Troubleshooting
170
+
171
+
**Containers won't start**: Check Docker logs with `docker compose logs [service-name]`
172
+
173
+
**Database migrations fail**: Ensure you're in the correct directory and have pnpm installed
174
+
175
+
**Private location not connecting**: Verify the `OPENSTATUS_KEY` and `OPENSTATUS_INGEST_URL` are correct
176
+
177
+
**Tinybird issues**: Make sure the Tinybird token is correctly set in `.env.docker`
178
+
179
+
## Next steps
180
+
181
+
- **[Deploy Private Locations](/guides/how-to-deploy-probes-cloudflare-containers)** - Set up monitoring from multiple regions
182
+
- **[Create Monitors](/tutorial/how-to-create-monitor)** - Start monitoring your services
183
+
- **[Configure Notifications](/monitoring/customization/notification)** - Get alerted on issues
184
+
185
+
## Additional resources
186
+
187
+
- **[Docker Compose file](https://github.com/openstatusHQ/openstatus/blob/main/docker-compose.yaml)** - Review the complete configuration
188
+
- **[Private Location Reference](/reference/private-location)** - Technical specifications
189
+
- **[Join our Discord](https://www.openstatus.dev/discord)** - Get help from the community
-21
apps/docs/src/content/docs/incident/incident-detail.mdx
-21
apps/docs/src/content/docs/incident/incident-detail.mdx
···
1
-
---
2
-
title: Incident Detail
3
-
description: "Discover the incident details in OpenStatus"
4
-
order: 2
5
-
---
6
-
7
-
import { Image } from 'astro:assets';
8
-
import IncidentDetail from '../../../assets/incident/incident-detail.png';
9
-
import { Aside } from '@astrojs/starlight/components';
10
-
11
-
12
-
On the incident page, you can see the details of the incident, the monitor that failed, and the duration.
13
-
We are also taking a screenshot of the monitor when the incident is created, and when it's resolved.
14
-
15
-
16
-
<Image
17
-
src={IncidentDetail}
18
-
alt="Incident page"
19
-
/>
20
-
21
-
<Aside>There might be a delay between the incident creation and the screenshot capture. Your endpoint could have already recovered.</Aside>
-11
apps/docs/src/content/docs/incident/overview.mdx
-11
apps/docs/src/content/docs/incident/overview.mdx
···
1
-
---
2
-
title: Overview
3
-
description: "Discover what is an incident in OpenStatus"
4
-
---
5
-
6
-
7
-
## What is an incident 🧑🏫
8
-
9
-
We automatically create an incident when we detect a problem with your service.
10
-
When a monitor fails in more than 50% of the locations, we create an incident.
11
-
We do that in order to avoid false positives.
-25
apps/docs/src/content/docs/incident/work-with-incident.mdx
-25
apps/docs/src/content/docs/incident/work-with-incident.mdx
···
1
-
---
2
-
title: Work with Incidents
3
-
description: "How to acknowledge and resolve incidents in OpenStatus"
4
-
---
5
-
6
-
An incident can have the following states:
7
-
8
-
- **On Going**: The incident is still active.
9
-
- **Acknowledged**: The incident has been acknowledged.
10
-
- **Resolved**: The incident has been resolved.
11
-
12
-
## How to acknowledge an incident
13
-
14
-
Go to the incident page and click on the acknowledge button.
15
-
16
-
## How to resolve an incident
17
-
18
-
Go to the incident page and click on the resolve button.
19
-
20
-
## Auto resolve an incident
21
-
22
-
We automatically resolve an incident when the monitor is passing in more than
23
-
50% of the locations.
24
-
25
-
+12
-6
apps/docs/src/content/docs/index.mdx
+12
-6
apps/docs/src/content/docs/index.mdx
···
14
14
15
15
### What is openstatus?
16
16
17
-
[openstatus](https://www.openstatus.dev) is an open-source status page platform with uptime monitoring.
17
+
[openstatus](https://www.openstatus.dev) is an open-source status page platform with uptime monitoring. Monitor your websites, APIs, and services from multiple global locations and share real-time status updates with your users.
18
18
19
-
### New to openstatus?
19
+
### How to use this documentation
20
20
21
+
Our documentation follows the [Diátaxis framework](https://diataxis.fr/), organizing content into four distinct categories to help you find what you need:
21
22
22
23
<CardGrid >
23
-
<LinkCard title="Concepts" href="/concept/getting-started/" description="Read about the concept behind OpenStatus" />
24
-
<LinkCard title="Tutorials" href="/tutorial/getting-started/" description="Read our tutorials to learn how to use OpenStatus" />
25
-
<LinkCard title="Guides" href="/guides/getting-started/" description="Some useful guides about openstatus" />
26
-
<LinkCard title="Help" href="/help/support/" description="Need help?" />
24
+
<LinkCard title="📚 Tutorials" href="/tutorial/getting-started/" description="Step-by-step lessons to learn openstatus from scratch. Start here if you're new!" />
25
+
<LinkCard title="🛠️ How-to Guides" href="/guides/getting-started/" description="Practical guides to solve specific problems and accomplish particular tasks." />
26
+
<LinkCard title="💡 Concepts" href="/concept/getting-started/" description="In-depth explanations of key concepts, design decisions, and best practices." />
27
+
<LinkCard title="📖 Reference" href="/reference" description="Technical specifications, API documentation, and configuration references." />
27
28
</CardGrid>
29
+
30
+
**Not sure where to start?**
31
+
- **New users**: Begin with our [tutorials](/tutorial/getting-started/) to create your first monitor
32
+
- **Experienced users**: Check out [how-to guides](/guides/getting-started/) for specific tasks
33
+
- **Need help?** Visit our [help section](/help/support/) or join our community
28
34
29
35
30
36
### Join the community
+1
-1
apps/docs/src/content/docs/monitoring/clone-monitor.mdx
+1
-1
apps/docs/src/content/docs/monitoring/clone-monitor.mdx
+1
-1
apps/docs/src/content/docs/monitoring/customization/assertions.mdx
+1
-1
apps/docs/src/content/docs/monitoring/customization/assertions.mdx
+2
-2
apps/docs/src/content/docs/monitoring/customization/follow-redirects.mdx
+2
-2
apps/docs/src/content/docs/monitoring/customization/follow-redirects.mdx
···
1
1
---
2
2
title: Follow Redirects
3
-
description: "What are follow redirects on a monitor in OpenStatus"
3
+
description: "What are follow redirects on a monitor in openstatus"
4
4
---
5
5
6
6
The Follow Redirects option controls whether your monitor should automatically follow HTTP redirects. **By default, we follow the redirects.**
···
9
9
10
10
Enable this option if:
11
11
- You are monitoring a URL that often redirects (e.g. from http:// to https://, or from a short link to the final page).
12
-
- You want to verify that the final destination is available and returns the expected response.
12
+
- You want to verify that the final destination is available and returns the expected response.
+2
-2
apps/docs/src/content/docs/monitoring/customization/frequency.mdx
+2
-2
apps/docs/src/content/docs/monitoring/customization/frequency.mdx
···
1
1
---
2
2
title: Frequency
3
-
description: "How to change the frequency of your synthetic checks in OpenStatus"
3
+
description: "How to change the frequency of your synthetic checks in openstatus"
4
4
---
5
5
6
-
By default, OpenStatus.dev will check your service every 30 minutes.
6
+
By default, openstatus.dev will check your service every 30 minutes.
7
7
8
8
The min frequency options range from 10 minutes for free plans to 30 seconds for paid plans.
9
9
+3
-3
apps/docs/src/content/docs/monitoring/customization/locations.mdx
+3
-3
apps/docs/src/content/docs/monitoring/customization/locations.mdx
···
1
1
---
2
2
title: Locations
3
-
description: "How to change the locations for your synthetic checks in OpenStatus"
3
+
description: "How to change the locations for your synthetic checks in openstatus"
4
4
---
5
5
6
6
···
8
8
9
9
## Public Locations
10
10
11
-
For free users, OpenStatus will monitor your service from six location, one on every continent. For paid users, you can choose from multiple locations around the world to monitor your service.
11
+
For free users, openstatus will monitor your service from six location, one on every continent. For paid users, you can choose from multiple locations around the world to monitor your service.
12
12
13
13
14
14
To change regions for your monitors: _Select a monitor → Settings → Scheduling & Regions_.
···
68
68
69
69
## Private Locations
70
70
71
-
You can also use private locations to monitor your services. Private locations are servers that you own and manage. If you want to use private locations, please [contact us](mailto:ping@openstatus.dev) for more information.
71
+
You can also use private locations to monitor your services. Private locations are servers that you own and manage. If you want to use private locations, you can learn how to set them up in our [How to create a private location (beta)](/tutorial/how-to-create-private-location) guide.
+1
-1
apps/docs/src/content/docs/monitoring/customization/notification.mdx
+1
-1
apps/docs/src/content/docs/monitoring/customization/notification.mdx
···
1
1
---
2
2
title: Notifications
3
-
description: "How to set up notifications for your synthetic checks in OpenStatus"
3
+
description: "How to set up notifications for your synthetic checks in openstatus"
4
4
---
5
5
import { Image } from 'astro:assets';
6
6
import { Aside} from '@astrojs/starlight/components';
+2
-2
apps/docs/src/content/docs/monitoring/customization/timing.mdx
+2
-2
apps/docs/src/content/docs/monitoring/customization/timing.mdx
···
1
1
---
2
2
title: Timing
3
-
description: "How to set up timing threshold for your synthetic checks in OpenStatus"
3
+
description: "How to set up timing threshold for your synthetic checks in openstatus"
4
4
---
5
5
6
-
By default, OpenStatus will timeout after `45s` but you can set a custom timeout (max. `45s`).
6
+
By default, openstatus will timeout after `45s` but you can set a custom timeout (max. `45s`).
7
7
8
8
You can also set a custom degraded threshold. If the response time is higher than the degraded threshold, the status will be set to `Degraded` and we will send a notification.
9
9
+3
-3
apps/docs/src/content/docs/monitoring/group-monitor-tag.mdx
+3
-3
apps/docs/src/content/docs/monitoring/group-monitor-tag.mdx
···
1
1
---
2
2
title: How to group your monitors
3
-
description: "How to group your monitors in OpenStatus to manage them more efficiently"
3
+
description: "How to group your monitors in openstatus to manage them more efficiently"
4
4
---
5
5
6
6
import { Image } from 'astro:assets';
···
16
16
17
17
<Image
18
18
src={createTag}
19
-
alt="OpenStatus create monitor tag"
19
+
alt="openstatus create monitor tag"
20
20
/>
21
21
22
22
···
26
26
27
27
<Image
28
28
src={filterTag}
29
-
alt="OpenStatus filter by tag"
29
+
alt="openstatus filter by tag"
30
30
/>
+5
-5
apps/docs/src/content/docs/monitoring/monitor-data-collected.mdx
+5
-5
apps/docs/src/content/docs/monitoring/monitor-data-collected.mdx
···
1
1
---
2
2
title: Monitor Data Points
3
-
description: "Monitor metrics are the data points that are collected by the monitor during the check in OpenStatus."
3
+
description: "Monitor metrics are the data points that are collected by the monitor during the check in openstatus."
4
4
---
5
5
6
6
import { Image } from 'astro:assets';
···
18
18
19
19
<Image
20
20
src={ResponseLog}
21
-
alt="OpenStatus response log"
21
+
alt="openstatus response log"
22
22
/>
23
23
24
24
···
33
33
34
34
<Image
35
35
src={ResponseLogHeader}
36
-
alt="OpenStatus response log"
36
+
alt="openstatus response log"
37
37
/>
38
38
39
39
···
52
52
53
53
<Image
54
54
src={ResponseLogTiming}
55
-
alt="OpenStatus response log timing"
55
+
alt="openstatus response log timing"
56
56
/>
57
57
58
58
### TCP Monitor Metrics
59
59
60
60
For a TCP monitor, the following metrics are collected:
61
61
- **Response Time**: The time taken by the server to respond to the request.
62
-
- **TCP timing**: The time taken to establish a TCP connection.
62
+
- **TCP timing**: The time taken to establish a TCP connection.
+5
-5
apps/docs/src/content/docs/monitoring/monitoring-as-code.mdx
+5
-5
apps/docs/src/content/docs/monitoring/monitoring-as-code.mdx
···
1
1
---
2
2
title: Monitoring as Code
3
-
description: "How to manage monitors as code with OpenStatus?"
3
+
description: "How to manage monitors as code with openstatus?"
4
4
---
5
5
6
6
## Introduction
···
14
14
15
15
## Getting Started
16
16
17
-
OpenStatus provides a [CLI](/tutorial/get-started-with-openstatus-cli) tool that allows you to create, update, and delete monitors as code. To get started, you need to install the CLI tool.
17
+
openstatus provides a [CLI](/tutorial/get-started-with-openstatus-cli) tool that allows you to create, update, and delete monitors as code. To get started, you need to install the CLI tool.
18
18
19
19
## Examples
20
20
···
39
39
url: https://openstat.us
40
40
method: GET
41
41
headers:
42
-
User-Agent: OpenStatus
42
+
User-Agent: openstatus
43
43
assertions:
44
44
- kind: statusCode
45
45
compare: eq
···
69
69
"method": "ping"
70
70
}
71
71
headers:
72
-
User-Agent: OpenStatus
72
+
User-Agent: openstatus
73
73
Accept: application/json, text/event-stream
74
74
Content-Type: application/json
75
75
assertions:
···
81
81
target: '{"result":{},"jsonrpc":"2.0","id":"openstatus"}'
82
82
```
83
83
84
-
You can find more examples in the [OpenStatus Template GitHub repository](https://github.com/openstatusHQ/cli-template/).
84
+
You can find more examples in the [openstatus Template GitHub repository](https://github.com/openstatusHQ/cli-template/).
+4
-4
apps/docs/src/content/docs/monitoring/opentelemetry.mdx
+4
-4
apps/docs/src/content/docs/monitoring/opentelemetry.mdx
···
1
1
---
2
2
title: OpenTelemetry
3
-
description: "How to export your synthetic monitoring data to your observability platform with OpenStatus"
3
+
description: "How to export your synthetic monitoring data to your observability platform with openstatus"
4
4
---
5
5
import { Aside } from '@astrojs/starlight/components';
6
6
···
10
10
11
11
12
12
13
-
## How to export your synthetic monitoring data to your observability stack with OpenStatus
13
+
## How to export your synthetic monitoring data to your observability stack with openstatus
14
14
15
15
16
-
OpenStatus supports exporting your synthetic monitoring data to your observability platform using OpenTelemetry.
16
+
openstatus supports exporting your synthetic monitoring data to your observability platform using OpenTelemetry.
17
17
18
18
When you enable this feature, we will export the results of the synthetic checks as metrics.
19
19
···
28
28
#### Grafana Cloud Example
29
29
30
30
31
-
[OpenStatus X Grafana Public dashboard](https://openstatus.grafana.net/public-dashboards/a85806536e9243f7ab9e0d458eb2ad32)
31
+
[openstatus X Grafana Public dashboard](https://openstatus.grafana.net/public-dashboards/a85806536e9243f7ab9e0d458eb2ad32)
32
32
33
33
### How to setup?
34
34
+29
-3
apps/docs/src/content/docs/monitoring/overview.mdx
+29
-3
apps/docs/src/content/docs/monitoring/overview.mdx
···
1
1
---
2
-
title: Overview
3
-
description: "Learn more about synthetic monitoring and how to use it with OpenStatus"
2
+
title: Monitoring Overview
3
+
description: "Introduction to synthetic monitoring with openstatus"
4
4
---
5
5
6
6
import { CardGrid, LinkCard } from '@astrojs/starlight/components';
7
7
import { Image } from 'astro:assets';
8
8
import overview from '../../../assets/monitor/overview/dashboard.png';
9
9
10
+
## What is synthetic monitoring?
11
+
10
12
With openstatus, you can simulate user requests to check the availability and performance of your website, API, or server from different locations around the globe. This proactive approach helps you find issues before your users do.
11
13
14
+
Synthetic monitoring complements real user monitoring (RUM) by providing:
15
+
- **Consistent baseline**: Predictable checks at regular intervals
16
+
- **Early warning system**: Detect issues before they affect many users
17
+
- **Global perspective**: Monitor from multiple regions simultaneously
18
+
- **24/7 coverage**: Continuous monitoring, even when you have no traffic
19
+
12
20
<Image
13
21
src={overview}
14
-
alt="Charts with status code and response time"
22
+
alt="openstatus dashboard showing status codes and response time charts"
15
23
/>
16
24
17
25
···
35
43
- Terraform: Automate the process with our [Terraform provider](/tools/terraform).
36
44
37
45
### Monitor types
46
+
47
+
We support different types of monitors for various use cases:
38
48
39
49
<CardGrid>
40
50
<LinkCard
41
51
title="HTTP Monitor"
42
52
href="/monitoring/type/http"
53
+
description="Monitor HTTP/HTTPS endpoints including APIs and websites"
43
54
/>
44
55
<LinkCard
45
56
title="TCP Monitor"
46
57
href="/monitoring/type/tcp"
58
+
description="Monitor TCP port availability for databases and services"
47
59
/>
48
60
</CardGrid>
61
+
62
+
## Getting started
63
+
64
+
Ready to start monitoring? Follow these guides:
65
+
66
+
1. **[Create Your First Monitor](/tutorial/how-to-create-monitor)** - Step-by-step tutorial
67
+
2. **[Configure Notifications](/monitoring/customization/notification)** - Get alerted on issues
68
+
3. **[Set Up Assertions](/monitoring/customization/assertions)** - Validate response content
69
+
70
+
## Learn more
71
+
72
+
- **[Understanding Uptime Monitoring](/concept/uptime-monitoring)** - Core concepts explained
73
+
- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - What metrics we track
74
+
- **[Monitoring as Code](/monitoring/monitoring-as-code)** - Manage monitors with YAML
+2
-2
apps/docs/src/content/docs/monitoring/type/http.mdx
+2
-2
apps/docs/src/content/docs/monitoring/type/http.mdx
···
1
1
---
2
2
title: HTTP
3
-
description: "How to monitor your HTTP services with OpenStatus"
3
+
description: "How to monitor your HTTP services with openstatus"
4
4
---
5
5
import { Image } from 'astro:assets';
6
6
···
35
35
36
36
When you select the `POST` method, you can add a body payload to your request. This is useful when you need to send data to your service.
37
37
38
-
Payloads are often JSON or XML, but we also support plain text or binary files.
38
+
Payloads are often JSON or XML, but we also support plain text or binary files.
+2
-2
apps/docs/src/content/docs/monitoring/type/tcp.mdx
+2
-2
apps/docs/src/content/docs/monitoring/type/tcp.mdx
···
1
1
---
2
2
title: TCP
3
-
description: "How to monitor your TCP services with OpenStatus"
3
+
description: "How to monitor your TCP services with openstatus"
4
4
---
5
5
6
6
import { Image } from 'astro:assets';
···
15
15
16
16
17
17
### URI (Host:Port)
18
-
Provide your Host and Port to monitor your TCP service. Could be a domain or IPv4/IPv6 address.
18
+
Provide your Host and Port to monitor your TCP service. Could be a domain or IPv4/IPv6 address.
+55
-2
apps/docs/src/content/docs/reference.mdx
+55
-2
apps/docs/src/content/docs/reference.mdx
···
1
1
---
2
-
title: About this project
3
-
description: Learn more about the project I’m working on.
2
+
title: Reference Documentation
3
+
description: Technical specifications, API documentation, and configuration references
4
4
---
5
+
6
+
import { CardGrid, LinkCard } from '@astrojs/starlight/components';
7
+
8
+
## 📖 Reference
9
+
10
+
Reference documentation provides **technical specifications** and detailed information about openstatus components, APIs, and configuration options. This is where you look up exact parameter names, return types, and available options.
11
+
12
+
### When to use reference docs
13
+
14
+
Reference documentation is ideal when you:
15
+
- Need to look up specific API endpoints or parameters
16
+
- Want to know all available configuration options
17
+
- Are looking for technical specifications
18
+
- Need to understand data structures and types
19
+
20
+
### Monitor Types
21
+
22
+
Detailed specifications for each monitor type:
23
+
24
+
<CardGrid>
25
+
<LinkCard title="HTTP Monitor" href="/reference/http-monitor" description="Complete reference for HTTP/HTTPS endpoint monitoring" />
26
+
<LinkCard title="TCP Monitor" href="/reference/tcp-monitor" description="TCP port monitoring specifications" />
27
+
<LinkCard title="DNS Monitor" href="/reference/dns-monitor" description="DNS resolution monitoring reference" />
28
+
</CardGrid>
29
+
30
+
### Components & Features
31
+
32
+
<CardGrid>
33
+
<LinkCard title="Status Page" href="/reference/status-page" description="Status page configuration options" />
34
+
<LinkCard title="Status Report" href="/reference/status-report" description="Status report specifications" />
35
+
<LinkCard title="Subscriber" href="/reference/subscriber" description="Status page subscriber reference" />
36
+
<LinkCard title="Incident" href="/reference/incident" description="Incident management reference" />
37
+
<LinkCard title="Notification" href="/reference/notification" description="Notification channel specifications" />
38
+
</CardGrid>
39
+
40
+
### Infrastructure & Tools
41
+
42
+
<CardGrid>
43
+
<LinkCard title="CLI Reference" href="/reference/cli-reference" description="Complete command-line interface documentation" />
44
+
<LinkCard title="Terraform Provider" href="/reference/terraform" description="Infrastructure as code with Terraform" />
45
+
<LinkCard title="Private Location" href="/reference/private-location" description="Self-hosted monitoring agent reference" />
46
+
</CardGrid>
47
+
48
+
### API Documentation
49
+
50
+
For programmatic access to openstatus:
51
+
- **[REST API](https://api.openstatus.dev/v1)** - Full REST API reference with interactive examples
52
+
53
+
### Related sections
54
+
55
+
- **[Tutorials](/tutorial/getting-started/)** - Learn how to use these features step-by-step
56
+
- **[How-to guides](/guides/getting-started/)** - Practical examples of common use cases
57
+
- **[Explanations](/concept/getting-started/)** - Understand the concepts behind the reference material
+10
-10
apps/docs/src/content/docs/reference/cli-reference.mdx
+10
-10
apps/docs/src/content/docs/reference/cli-reference.mdx
···
4
4
5
5
## CLI interface - openstatus
6
6
7
-
OpenStatus is a command line interface for managing your monitors and triggering your synthetics tests.
7
+
openstatus is a command line interface for managing your monitors and triggering your synthetics tests.
8
8
9
-
This is OpenStatus Command Line Interface, the OpenStatus.dev CLI.
9
+
This is openstatus Command Line Interface, the openstatus.dev CLI.
10
10
11
11
Usage:
12
12
···
30
30
31
31
> openstatus monitors apply [options]
32
32
33
-
Creates or updates monitors according to the OpenStatus configuration file.
33
+
Creates or updates monitors according to the openstatus configuration file.
34
34
35
35
Usage:
36
36
···
43
43
| Name | Description | Default value | Environment variables |
44
44
|-----------------------------|-------------------------------------------------------|:-----------------:|:----------------------:|
45
45
| `--config="…"` (`-c`) | The configuration file containing monitor information | `openstatus.yaml` | *none* |
46
-
| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
46
+
| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |
47
47
| `--auto-accept` (`-y`) | Automatically accept the prompt | `false` | *none* |
48
48
49
49
···
65
65
66
66
| Name | Description | Default value | Environment variables |
67
67
|-----------------------------|-----------------------------|:-----------------:|:----------------------:|
68
-
| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
68
+
| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |
69
69
| `--output="…"` (`-o`) | The output file name | `openstatus.yaml` | *none* |
70
70
71
71
### `monitors info` subcommand
···
86
86
87
87
| Name | Description | Default value | Environment variables |
88
88
|-----------------------------|-----------------------------|:-------------:|:----------------------:|
89
-
| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
89
+
| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |
90
90
91
91
### `monitors list` subcommand
92
92
···
107
107
| Name | Description | Default value | Environment variables |
108
108
|-----------------------------|-------------------------------------------|:-------------:|:----------------------:|
109
109
| `--all` | List all monitors including inactive ones | `false` | *none* |
110
-
| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
110
+
| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |
111
111
112
112
### `monitors trigger` subcommand
113
113
···
127
127
128
128
| Name | Description | Default value | Environment variables |
129
129
|-----------------------------|-----------------------------|:-------------:|:----------------------:|
130
-
| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
130
+
| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |
131
131
132
132
### `run` command (aliases: `r`)
133
133
···
148
148
| Name | Description | Default value | Environment variables |
149
149
|-----------------------------|-----------------------------|:------------------------:|:----------------------:|
150
150
| `--config="…"` | The configuration file | `config.openstatus.yaml` | *none* |
151
-
| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
151
+
| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |
152
152
153
153
### `whoami` command (aliases: `w`)
154
154
···
168
168
169
169
| Name | Description | Default value | Environment variables |
170
170
|-----------------------------|-----------------------------|:-------------:|:----------------------:|
171
-
| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
171
+
| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |
+124
-13
apps/docs/src/content/docs/reference/dns-monitor.mdx
+124
-13
apps/docs/src/content/docs/reference/dns-monitor.mdx
···
1
1
---
2
-
title: DNS Monitor
2
+
title: DNS Monitor Reference
3
+
description: Complete technical specification for DNS record monitoring
3
4
---
4
5
5
-
A DNS Monitor is a component that allows you to monitor the status of DNS records. It can be used to monitor the status of a domain name, a subdomain, or any other DNS record.
6
+
## Overview
6
7
7
-
It will fetch the following DNS record types:
8
-
- A
9
-
- AAAA
10
-
- CNAME
11
-
- MX
12
-
- NS
13
-
- TXT
8
+
A DNS Monitor is a component designed to verify the availability and correctness of DNS records. It performs periodic lookups for specified DNS record types against a target domain or subdomain from various geographical locations.
9
+
10
+
**Use cases:**
11
+
- Validating domain name resolution
12
+
- Monitoring changes to critical DNS records (e.g., A, CNAME, MX)
13
+
- Ensuring proper load balancing via DNS (when combined with multi-region checks)
14
+
- Detecting unauthorized DNS alterations
14
15
15
16
## Configuration
16
17
17
-
### URI
18
-
The domain or subdomain you want to monitor e.g `openstat.us`
18
+
### URI
19
+
20
+
**Type:** String (required)
21
+
**Format:** Domain name or subdomain
22
+
23
+
The fully qualified domain name or subdomain to be monitored.
24
+
25
+
**Examples:**
26
+
- `openstat.us`
27
+
- `api.example.com`
28
+
- `mail.example.org`
29
+
30
+
### Record Types
31
+
32
+
The monitor supports fetching and validating the following DNS record types:
33
+
34
+
- `A` (Address Record): Maps a domain name to an IPv4 address.
35
+
- `AAAA` (IPv6 Address Record): Maps a domain name to an IPv6 address.
36
+
- `CNAME` (Canonical Name Record): Maps an alias domain name to another canonical domain name.
37
+
- `MX` (Mail Exchange Record): Specifies the mail servers responsible for accepting email messages on behalf of a domain name.
38
+
- `NS` (Name Server Record): Delegates a domain or subdomain to a set of authoritative name servers.
39
+
- `TXT` (Text Record): Carries arbitrary human-readable text and is also used for various purposes like SPF, DKIM, DMARC, and site verification.
40
+
41
+
### Regions
42
+
43
+
The geographical locations from which the DNS monitoring checks are performed. This allows for verification of DNS propagation and performance across different networks.
44
+
45
+
__Africa__
46
+
47
+
- Johannesburg, South Africa 🇿🇦 (free)
48
+
49
+
__Asia__
50
+
51
+
- Hong Kong, Hong Kong 🇭🇰 (free)
52
+
- Mumbai, India 🇮🇳
53
+
- Singapore, Singapore 🇸🇬
54
+
- Tokyo, Japan 🇯🇵
55
+
56
+
__Europe__
57
+
58
+
- Amsterdam, Netherlands 🇳🇱 (free)
59
+
- Bucharest, Romania 🇷🇴
60
+
- Frankfurt, Germany 🇩🇪
61
+
- London, United Kingdom 🇬🇧
62
+
- Madrid, Spain 🇪🇸
63
+
- Paris, France 🇫🇷
64
+
- Stockholm, Sweden 🇸🇪
65
+
- Warsaw, Poland 🇵🇱
66
+
67
+
__North America__
19
68
20
-
### Regions
69
+
- Ashburn, Virginia, USA 🇺🇸 (free)
70
+
- Atlanta, Georgia, USA 🇺🇸
71
+
- Boston, Massachusetts, USA 🇺🇸
72
+
- Chicago, Illinois, USA 🇺🇸
73
+
- Dallas, Texas, USA 🇺🇸
74
+
- Denver, Colorado, USA 🇺🇸
75
+
- Guadalajara, Mexico 🇲🇽
76
+
- Los Angeles, California, USA 🇺🇸
77
+
- Miami, Florida, USA 🇺🇸
78
+
- Montreal, Canada 🇨🇦
79
+
- Phoenix, Arizona, USA 🇺🇸
80
+
- Queretaro, Mexico 🇲🇽
81
+
- Seattle, Washington, USA 🇺🇸
82
+
- San Jose, California, USA 🇺🇸
83
+
- Toronto, Canada 🇨🇦
84
+
85
+
__South America__
86
+
87
+
- Bogota, Colombia 🇨🇴
88
+
- Buenos Aires, Argentina 🇦🇷
89
+
- Rio de Janeiro, Brazil 🇧🇷
90
+
- Sao Paulo, Brazil 🇧🇷 (free)
91
+
- Santiago, Chile 🇨🇱
21
92
22
-
The regions where we are triggering the DNS request.
93
+
__Oceania__
94
+
95
+
- Sydney, Australia 🇦🇺 (free)
96
+
97
+
### Frequency
98
+
99
+
The interval at which the DNS checks are performed. Supported frequencies:
100
+
- 30 seconds
101
+
- 1 minute
102
+
- 5 minutes
103
+
- 10 minutes
104
+
- 30 minutes
105
+
- 1 hour
106
+
107
+
### Response Time Thresholds
108
+
109
+
#### Timeout
110
+
111
+
**Type:** Duration (optional)
112
+
**Default:** `45 seconds`
113
+
114
+
The maximum duration to wait for a DNS response. If the lookup exceeds this time, the check is considered failed.
115
+
116
+
#### Degraded
117
+
118
+
**Type:** Duration (optional)
119
+
120
+
The duration after which a DNS response is considered degraded. This indicates a performance issue without being a complete failure.
121
+
122
+
### Retry
123
+
124
+
**Type:** Integer (optional)
125
+
**Default:** `3`
126
+
127
+
The number of times the monitor will retry a failed DNS lookup before reporting a definitive failure. For example: `3`
128
+
129
+
## Related resources
130
+
131
+
- **[Monitoring Overview](/monitoring/overview)** - Conceptual overview of monitoring within OpenStatus.
132
+
- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - Details on all metrics collected by monitors.
133
+
- **[CLI Reference](/reference/cli-reference)** - Manage monitors as code using the OpenStatus CLI.
+187
-56
apps/docs/src/content/docs/reference/http-monitor.mdx
+187
-56
apps/docs/src/content/docs/reference/http-monitor.mdx
···
1
1
---
2
-
title: HTTP Monitor
2
+
title: HTTP Monitor Reference
3
+
description: Complete technical specification for HTTP/HTTPS endpoint monitoring
3
4
---
4
5
5
-
An HTTP Monitor is a component that allows you to monitor the status of HTTP endpoints. It can be used to monitor the status of a website, an API, or any other HTTP endpoint.
6
+
## Overview
7
+
8
+
An HTTP Monitor is a component that allows you to monitor the status of HTTP and HTTPS endpoints. It can be used to monitor websites, APIs, webhooks, or any other HTTP-accessible service.
9
+
10
+
**Use cases:**
11
+
- Website uptime monitoring
12
+
- API health checks
13
+
- Webhook endpoint validation
14
+
- CDN performance monitoring
15
+
- Authentication endpoint testing
6
16
7
17
## Configuration
8
18
9
19
### URL
10
20
11
-
The url of the HTTP endpoint you want to monitor e.g `https://openstat.us`
21
+
**Type:** String (required)
22
+
**Format:** Full URL including protocol
23
+
24
+
The URL of the HTTP endpoint you want to monitor.
25
+
26
+
**Examples:**
27
+
- `https://openstat.us`
28
+
- `https://api.example.com/health`
29
+
- `http://internal-service.local:8080/status`
30
+
31
+
**Note:** We recommend using HTTPS for better security.
12
32
13
33
### Methods
14
34
15
-
The HTTP method you want to use to monitor the endpoint.
16
-
- `GET`
17
-
- `POST`
18
-
- `PUT`
19
-
- `DELETE`
20
-
- `HEAD`
21
-
- `OPTIONS`
22
-
- `PATCH`
23
-
- `TRACE`
35
+
**Type:** String (required)
36
+
**Default:** `GET`
37
+
38
+
The HTTP method to use when making the request to the endpoint.
39
+
40
+
**Available methods:**
41
+
- `GET` - Retrieve data (most common for health checks)
42
+
- `POST` - Send data to create/trigger actions
43
+
- `PUT` - Update existing resources
44
+
- `DELETE` - Remove resources
45
+
- `HEAD` - Like GET but without response body
46
+
- `OPTIONS` - Query supported methods
47
+
- `PATCH` - Partial resource updates
48
+
- `TRACE` - Echo request for debugging
49
+
50
+
**Common usage:**
51
+
- Health checks: `GET`
52
+
- API testing: `POST`, `PUT`, `DELETE`
53
+
- Webhook testing: `POST`
24
54
25
55
### Body
26
56
27
-
The body of the HTTP request you want to send to the endpoint. You use binary data if the content type is `application/octet-stream`.
28
-
Example:
29
-
- `{ "key": "value" }`
30
-
- `data:image/jpeg;base64,/9j...`
57
+
**Type:** String (optional)
58
+
**Available for:** `POST`, `PUT`, `PATCH` methods
59
+
60
+
The request body to send with the HTTP request. Supports both text and binary data.
61
+
62
+
**Text body examples:**
63
+
```json
64
+
{ "key": "value" }
65
+
```
66
+
67
+
**Binary data:**
68
+
For binary content (e.g., images), use base64 encoding with data URI:
69
+
```
70
+
data:image/jpeg;base64,/9j...
71
+
```
72
+
73
+
**Content type:** Set the appropriate `Content-Type` header (e.g., `application/json`, `application/octet-stream`).
31
74
### Headers
32
75
33
-
The headers you want to send with the HTTP request
76
+
**Type:** Key-value pairs (optional)
77
+
78
+
Custom HTTP headers to include with your request.
79
+
80
+
**Common examples:**
81
+
```
82
+
Content-Type: application/json
83
+
Authorization: Bearer your_token_here
84
+
Accept: application/json
85
+
User-Agent: Custom-Agent/1.0
86
+
```
87
+
88
+
**Use cases:**
89
+
- **Authentication:** Send API tokens or credentials
90
+
- **Content negotiation:** Specify accepted response formats
91
+
- **Custom identification:** Add tracking or debugging headers
34
92
35
-
Example:
36
-
- `"Content-Type": "application/json"`
37
-
- `'Content-Type: application/octet-stream'`
93
+
**Note:** openstatus automatically adds `User-Agent: openstatus/1.0` to all requests.
38
94
39
95
### Regions
40
96
41
-
The regions where we are triggering the HTTP request.
97
+
**Type:** Array of Strings (required)
98
+
**Format:** Region identifiers (e.g., `iad`, `jnb`)
99
+
100
+
The geographical regions from which the HTTP request will be triggered. This allows for monitoring global availability and performance.
42
101
43
102
__Africa__
44
103
···
94
153
95
154
### Frequency
96
155
97
-
The check interval, we support the following frequencies:
98
-
- 30 seconds
99
-
- 1 minute
100
-
- 5 minutes
101
-
- 10 minutes
102
-
- 30 minutes
103
-
- 1 hour
156
+
**Type:** String (required)
157
+
**Format:** Duration string (e.g., `30s`, `1m`, `1h`)
158
+
159
+
The interval at which the HTTP monitor will perform checks. Supported frequencies:
160
+
- `30 seconds`
161
+
- `1 minute`
162
+
- `5 minutes`
163
+
- `10 minutes`
164
+
- `30 minutes`
165
+
- `1 hour`
104
166
105
167
### Response Time Thresholds
168
+
106
169
#### Timeout
107
-
The timeout for the HTTP request, default is `45 seconds`
170
+
171
+
**Type:** Duration (optional)
172
+
**Default:** `45 seconds`
173
+
174
+
The maximum duration to wait for the HTTP request to complete. If the request exceeds this time, it is considered a failure.
175
+
108
176
#### Degraded
109
-
The duration for which the HTTP request is considered degraded.
177
+
178
+
**Type:** Duration (optional)
179
+
180
+
The duration after which the HTTP request is considered to be performing in a degraded state. This threshold allows for proactive alerting on performance issues before a complete outage.
110
181
111
182
### Retry
112
-
The number of retries for the HTTP request. For example: `3`
183
+
184
+
**Type:** Integer (optional)
185
+
**Default:** `3`
186
+
187
+
The number of times the monitor will automatically retry the HTTP request upon failure before reporting a definitive error. For example: `3`
113
188
114
189
### Assertions
115
-
#### Body assertions
116
-
Validate the body of the response. The comparisons are:
117
-
- Contains
118
-
- Not Contains
119
-
- Equal
120
-
- Not Equal
121
-
- Empty
190
+
191
+
Assertions allow you to validate specific aspects of the HTTP response.
192
+
193
+
#### Body Assertions
194
+
195
+
Validate the content of the HTTP response body.
196
+
197
+
**Comparisons:**
198
+
- `Contains`: The response body must include the specified string.
199
+
- `Not Contains`: The response body must not include the specified string.
200
+
- `Equal`: The response body must exactly match the specified string.
201
+
- `Not Equal`: The response body must not exactly match the specified string.
202
+
- `Empty`: The response body must be empty.
203
+
204
+
#### Status Code Assertions
205
+
206
+
Validate the HTTP status code of the response.
122
207
123
-
#### Status code assertions
124
-
Validate the status code of the response. The comparisons are:
125
-
- Equal
126
-
- Not Equal
127
-
- Greater Than
128
-
- Greater Than or Equal
129
-
- Less Than
130
-
- Less Than or Equal
208
+
**Comparisons:**
209
+
- `Equal`: The status code must be exactly the specified value.
210
+
- `Not Equal`: The status code must not be the specified value.
211
+
- `Greater Than`: The status code must be greater than the specified value.
212
+
- `Greater Than or Equal`: The status code must be greater than or equal to the specified value.
213
+
- `Less Than`: The status code must be less than the specified value.
214
+
- `Less Than or Equal`: The status code must be less than or equal to the specified value.
215
+
216
+
#### Headers Assertions
217
+
218
+
Validate the presence or content of specific HTTP response headers.
219
+
220
+
**Purpose:** Verify cache headers, check security headers (e.g., `X-Frame-Options`), validate content-type.
221
+
222
+
**Comparisons:**
223
+
- `Contains`: A header's value must include the specified string.
224
+
- `Not Contains`: A header's value must not include the specified string.
225
+
- `Equal`: A header's value must exactly match the specified string.
226
+
- `Not Equal`: A header's value must not exactly match the specified string.
227
+
- `Empty`: A header's value must be empty or the header must not be present.
131
228
132
-
#### Headers assertions
133
-
Validate the headers of the reponse. The comparisons are:
134
-
- Contains
135
-
- Not Contains
136
-
- Equal
137
-
- Not Equal
138
-
- Empty
229
+
**Example Use Cases:**
230
+
- Verify `Cache-Control` headers are present and correct.
231
+
- Check for the existence of security-related headers like `Strict-Transport-Security`.
232
+
- Validate the `Content-Type` header in API responses.
139
233
140
234
### OpenTelemetry
235
+
236
+
Configures the export of monitoring metrics to an OpenTelemetry-compatible observability platform.
237
+
141
238
#### OTLP Endpoint
142
-
The endpoint we use to export the metrics. We only support HTTP endpoint.
239
+
240
+
**Type:** String (optional)
241
+
**Protocol:** HTTP only
242
+
243
+
The OTLP (OpenTelemetry Protocol) endpoint URL where collected metrics should be exported.
244
+
245
+
**Example:** `https://otlp.example.com/v1/metrics`
246
+
143
247
#### OTLP Headers
144
-
The headers we use to export the metrics to your otlp endpoint.
248
+
249
+
**Type:** Key-value pairs (optional)
250
+
251
+
Custom headers to include when sending metrics to your OTLP endpoint. Commonly used for authentication or tenant identification.
252
+
253
+
**Common example:**
254
+
```
255
+
Authorization: Bearer <your_token>
256
+
```
145
257
146
258
### Public
147
-
If set to true the monitors data is accessible on the status page (default:`false`)
259
+
260
+
**Type:** Boolean
261
+
**Default:** `false`
262
+
263
+
Controls the visibility of monitor data on your public status page.
264
+
265
+
- `true`: Monitor metrics and status are visible to all visitors of your status page.
266
+
- `false`: Monitor data remains private, accessible only within your OpenStatus dashboard.
267
+
268
+
**Use cases for public visibility:**
269
+
- Enhancing transparency with users regarding service health.
270
+
- Providing public API status pages.
271
+
- Displaying SaaS service availability to customers.
272
+
273
+
## Related resources
274
+
275
+
- **[Create Your First Monitor](/tutorial/how-to-create-monitor)** - Step-by-step tutorial on setting up a monitor.
276
+
- **[Monitoring Overview](/monitoring/overview)** - Conceptual overview of OpenStatus monitoring capabilities.
277
+
- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - Detailed information on all metrics and data points collected by monitors.
278
+
- **[CLI Reference](/reference/cli-reference)** - Guide to managing OpenStatus monitors programmatically using the command-line interface.
+41
-3
apps/docs/src/content/docs/reference/incident.mdx
+41
-3
apps/docs/src/content/docs/reference/incident.mdx
···
1
1
---
2
-
title: Incident
2
+
title: Incident Reference
3
+
description: Technical specification for incident management and lifecycle
3
4
---
4
5
5
-
An incident is a problem related to a monitor. They are created automatically when a monitor fails.
6
+
## Overview
7
+
8
+
An incident in OpenStatus represents a detected problem or service disruption related to a monitored resource. Incidents are automatically generated when a monitor reports a failure condition that meets predefined criteria. They serve as a central point for tracking, managing, and resolving service impairments.
6
9
7
-
At least 50% must have failed to trigger the incident.
10
+
**Key characteristics:**
11
+
- Automatically triggered by monitor failures.
12
+
- Aggregates related failure events for a single monitor.
13
+
- Provides a clear status of service health.
14
+
15
+
## Incident Triggering
16
+
17
+
An incident is triggered when a significant percentage of recent monitoring checks for a given monitor report a failed status. This mechanism prevents false positives from transient network issues.
18
+
19
+
**Trigger Condition:**
20
+
- **Failure Threshold:** An incident is initiated when at least 50% of the checks within a defined window (e.g., the last `N` checks or within a `T` duration) have reported a `failure` or `degraded` status.
21
+
22
+
## Incident Lifecycle and States
23
+
24
+
Incidents progress through several states reflecting their current resolution status. These states are managed through status reports (see [Status Report Reference](/reference/status-report)).
25
+
26
+
**Primary States:**
27
+
- `investigating`: The incident has been detected, and the team is actively looking into the root cause.
28
+
- `identified`: The root cause of the incident has been identified.
29
+
- `monitoring`: A fix has been deployed or a mitigation is in place, and the service is being monitored to confirm resolution.
30
+
- `resolved`: The incident has been fully resolved, and the service is operating normally.
31
+
32
+
## Properties
33
+
34
+
While an incident is active, it collects and displays key information related to the service disruption.
35
+
36
+
- **Monitor Association:** Each incident is directly linked to the monitor that triggered it, providing immediate context to the affected service.
37
+
- **Start Time:** Timestamp indicating when the incident was first detected and created.
38
+
- **Status Reports:** A chronological log of all updates and state changes applied to the incident.
39
+
- **Impacted Locations:** Details on the geographical regions from which the monitor reported failures.
40
+
41
+
## Related resources
42
+
43
+
- **[Status Report Reference](/reference/status-report)** - Details on how incident statuses are managed and reported.
44
+
- **[Monitoring Overview](/monitoring/overview)** - Conceptual overview of monitoring within OpenStatus.
45
+
- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - All tracked metrics collected by monitors.
+89
-42
apps/docs/src/content/docs/reference/notification.mdx
+89
-42
apps/docs/src/content/docs/reference/notification.mdx
···
1
1
---
2
-
title: Notification
2
+
title: Notification Channels Reference
3
+
description: Technical specification for OpenStatus notification channels and alert payloads.
3
4
---
4
5
5
-
A notification is a channel that is used to send alerts when your monitor status changes. By default no notifications are created in your workspace.
6
+
## Overview
7
+
8
+
Notifications in OpenStatus provide real-time alerts regarding changes in monitor status, such as recovery from an outage or detection of a new failure. By default, no notification channels are configured in a new workspace. Users must configure and enable specific channels to receive alerts.
6
9
10
+
## Notification Channels
7
11
8
-
## Notification Channels:
12
+
Each notification channel requires specific configuration parameters to enable alert delivery.
9
13
10
14
### Slack
11
15
12
-
Require a [Slack incoming webhook](https://api.slack.com/incoming-webhooks)
16
+
Integrates with Slack to send alerts to a designated channel.
17
+
18
+
**Configuration:**
19
+
- **Incoming Webhook URL:** (Required) A [Slack incoming webhook URL](https://api.slack.com/incoming-webhooks) where notifications will be posted.
13
20
14
21
### Email
15
22
16
-
Require an email address
23
+
Sends alerts directly to a specified email address.
24
+
25
+
**Configuration:**
26
+
- **Email Address:** (Required) The recipient's email address.
17
27
18
28
### Discord
19
29
20
-
Require a [discord webhook](https://support.discord.com/hc/en-us/articles/228383668
21
-
) e.g. `https://discordapp.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz1234567890`
30
+
Delivers alerts to a Discord channel via a webhook.
31
+
32
+
**Configuration:**
33
+
- **Webhook URL:** (Required) A [Discord webhook URL](https://support.discord.com/hc/en-us/articles/228383668) for the target channel.
34
+
**Example:** `https://discordapp.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz1234567890`
22
35
23
36
### Google Chat
24
37
25
-
Require a [Google Chat webhook](https://developers.google.com/workspace/chat/quickstart/webhooks)
38
+
Sends notifications to a Google Chat space.
39
+
40
+
**Configuration:**
41
+
- **Webhook URL:** (Required) A [Google Chat webhook URL](https://developers.google.com/workspace/chat/quickstart/webhooks) for the target space.
42
+
26
43
### SMS
27
44
28
-
Require a phone number (international format e.g. +14155552671)
45
+
Sends alerts as SMS messages to a mobile phone number.
46
+
47
+
**Configuration:**
48
+
- **Phone Number:** (Required) The recipient's phone number in international format (e.g., `+14155552671`).
29
49
30
-
Due to provider routing, SMS may not be delivered to all countries. Please contact support if you encounter any issues. Or use whatsapp notification instead.
50
+
**Note:** SMS delivery can vary by country due to provider routing. Contact support if delivery issues are encountered. WhatsApp notifications may be an alternative.
31
51
32
52
### WhatsApp
33
53
34
-
Require a phone number (international format e.g. +14155552671)
54
+
Sends alerts as WhatsApp messages to a mobile phone number.
35
55
56
+
**Configuration:**
57
+
- **Phone Number:** (Required) The recipient's phone number in international format (e.g., `+14155552671`).
36
58
37
59
### Telegram
38
60
39
-
Requires to know the chat id.
61
+
Delivers alerts to a specified Telegram chat.
40
62
41
-
> This integration is fully functional but accessing the chat id is not smooth yet. It requires manual effort to access your chat id. **You can ask RawDataBot `@raw_info_bot` for your chat id.**
63
+
**Configuration:**
64
+
- **Chat ID:** (Required) The unique identifier for the Telegram chat. This typically requires manual retrieval; users can ask `@raw_info_bot` for their chat ID.
42
65
43
-
The bot's id is `@openstatushq_bot` to make sure you are getting the correct notifications.
66
+
**Bot ID:** The official OpenStatus Telegram bot ID is `@openstatushq_bot`.
44
67
45
68
### Webhook
46
69
47
-
- URL (require)
48
-
- Headers (optional)
70
+
Sends HTTP POST requests to a custom endpoint with a JSON payload.
71
+
72
+
**Configuration:**
73
+
- **URL:** (Required) The endpoint URL to which the webhook payload will be sent.
74
+
- **Headers:** (Optional) Custom HTTP headers to include with the webhook request (key-value pairs).
49
75
50
76
#### Notification Payloads
51
77
52
-
##### Payload for Monitor Recovery
78
+
Webhook notifications utilize specific JSON payloads for different monitor status changes.
79
+
80
+
##### Monitor Recovery Payload
81
+
82
+
Sent when a monitor recovers from a `degraded` or `error` state.
53
83
54
84
```json
55
85
{
···
65
95
}
66
96
```
67
97
98
+
**Payload Fields:**
68
99
69
-
Fields Explanation:
70
-
- monitor: Contains details about the monitor.
71
-
- id: Unique identifier for the monitor.
72
-
- name: Name of the monitor.
73
-
- url: The URL being monitored.
74
-
- cronTimestamp: The timestamp when the check was executed, in milliseconds since epoch.
75
-
- status: Indicates the current status of the monitor (in this case, "recovered").
76
-
- statusCode: The HTTP status code returned by the monitored service.
77
-
- latency: The time taken to complete the check, in milliseconds.
100
+
| Field | Type | Description |
101
+
| :------------ | :------- | :------------------------------------------------------------------- |
102
+
| `monitor.id` | `number` | Unique identifier of the monitor. |
103
+
| `monitor.name`| `string` | Name of the monitor. |
104
+
| `monitor.url` | `string` | The URL or URI being monitored. |
105
+
| `cronTimestamp`| `number` | Timestamp of the check execution in milliseconds since epoch. |
106
+
| `status` | `string` | Indicates the monitor status: `"recovered"`. |
107
+
| `statusCode` | `number` | (Optional) HTTP status code returned by the monitored service. |
108
+
| `latency` | `number` | (Optional) Time taken to complete the check in milliseconds. |
78
109
110
+
##### Monitor Failure Payload
79
111
80
-
##### Payload for Monitor Failure
112
+
Sent when a monitor enters an `error` or `degraded` state.
81
113
82
114
```json
83
115
{
···
92
124
}
93
125
```
94
126
95
-
Fields Explanation:
127
+
**Payload Fields:**
96
128
97
-
- monitor: Contains details about the monitor.
98
-
- id: Unique identifier for the monitor.
99
-
- name: Name of the monitor.
100
-
- url: The URL being monitored.
101
-
- cronTimestamp: The timestamp when the check was executed, in milliseconds since epoch.
102
-
- status: Indicates the current status of the monitor (in this case, "error").
103
-
- errorMessage: A description of the error encountered during the check.
104
-
129
+
| Field | Type | Description |
130
+
| :------------ | :------- | :------------------------------------------------------------------- |
131
+
| `monitor.id` | `number` | Unique identifier of the monitor. |
132
+
| `monitor.name`| `string` | Name of the monitor. |
133
+
| `monitor.url` | `string` | The URL or URI being monitored. |
134
+
| `cronTimestamp`| `number` | Timestamp of the check execution in milliseconds since epoch. |
135
+
| `status` | `string` | Indicates the monitor status: `"degraded"` or `"error"`. |
136
+
| `errorMessage`| `string` | (Optional) A description of the error encountered during the check. |
105
137
106
138
#### Zod Schema
107
139
140
+
The validation schema for webhook payloads:
108
141
109
142
```ts
110
143
import { z } from "zod";
···
121
154
latency: z.number().optional(),
122
155
errorMessage: z.string().optional(),
123
156
});
124
-
````
157
+
```
125
158
126
159
### OpsGenie
127
160
128
-
- API key from OpsGenie (required)
161
+
Integrates with OpsGenie for incident management.
162
+
163
+
**Configuration:**
164
+
- **API Key:** (Required) An API key obtained from your OpsGenie account.
129
165
130
166
### PagerDuty
131
167
132
-
Follow the step in PagerDuty workflow
168
+
Integrates with PagerDuty for incident alerting.
169
+
170
+
**Configuration:**
171
+
- **Integration Steps:** (Required) Follow the specific integration steps provided within the PagerDuty workflow to set up this channel.
133
172
134
173
### Ntfy
135
174
136
-
- Ntfy topic (required)
137
-
- Custom server url (optional)
138
-
- bearer token (optional)
175
+
Sends notifications to an Ntfy topic.
176
+
177
+
**Configuration:**
178
+
- **Ntfy Topic:** (Required) The topic name to which notifications will be published.
179
+
- **Custom Server URL:** (Optional) The URL of a custom Ntfy server if not using the default.
180
+
- **Bearer Token:** (Optional) An authentication token for accessing the Ntfy server.
181
+
182
+
## Related resources
183
+
184
+
- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - Details on all metrics collected by monitors.
185
+
- **[Incident Reference](/reference/incident)** - Information about incident creation and management.
+39
-3
apps/docs/src/content/docs/reference/private-location.mdx
+39
-3
apps/docs/src/content/docs/reference/private-location.mdx
···
1
1
---
2
-
title: Private Location
2
+
title: Private Location Reference
3
+
description: Technical specification for configuring and utilizing private monitoring locations.
3
4
---
4
-
A private location is a location that you can set up within your own infrastructure to run monitoring checks from there.
5
+
6
+
## Overview
7
+
8
+
A private location in OpenStatus enables users to deploy monitoring probes within their own infrastructure or private networks. This capability is essential for monitoring internal services, APIs, or systems that are not publicly accessible from the internet, such as those behind firewalls or within a Virtual Private Cloud (VPC).
9
+
10
+
**Key benefits:**
11
+
- **Internal Monitoring:** Monitor services running on private networks.
12
+
- **Security:** Keep sensitive internal endpoints protected from public exposure.
13
+
- **Compliance:** Meet specific regulatory or security compliance requirements by controlling data paths.
14
+
- **Reduced Latency:** Conduct checks closer to your services for more accurate performance metrics.
5
15
16
+
## How it Works
6
17
7
-
For example this is useful if you want to monitor services that are not publicly accessible, such as internal APIs or services behind a firewall.
18
+
When a private location is configured, OpenStatus provides a mechanism (e.g., a container image or agent) that you deploy within your private environment. This deployed component acts as a local monitoring probe, executing checks on behalf of your OpenStatus account.
19
+
20
+
1. **Deployment:** You deploy the OpenStatus private probe within your chosen infrastructure (e.g., a Docker container on a server, a Kubernetes pod).
21
+
2. **Secure Connection:** The private probe establishes a secure, outbound-only connection to the OpenStatus platform, eliminating the need for inbound firewall rules.
22
+
3. **Check Execution:** OpenStatus dispatches monitoring tasks to your private probe via this secure connection. The probe then executes the configured checks against your internal services.
23
+
4. **Result Reporting:** The private probe securely sends the monitoring results (e.g., status, latency, response data) back to the OpenStatus platform for processing, alerting, and visualization.
24
+
25
+
## Configuration
26
+
27
+
Detailed steps for setting up a private location involve:
28
+
29
+
1. **Probe Deployment:** Provisioning a server or container environment within your private network.
30
+
2. **Agent Installation:** Deploying the OpenStatus private probe agent (e.g., Docker image) onto your infrastructure.
31
+
3. **Authentication:** Configuring the probe with necessary API keys or tokens to securely authenticate with your OpenStatus workspace.
32
+
4. **Network Access:** Ensuring the deployed probe has network access to the internal services it needs to monitor, as well as outbound access to the OpenStatus platform.
33
+
34
+
**Example Use Cases:**
35
+
- Monitoring an internal REST API that is only accessible from within your corporate network.
36
+
- Checking the health of a database server running on a private subnet.
37
+
- Performing synthetic transactions on an internal web application before it's exposed publicly.
38
+
39
+
## Related resources
40
+
41
+
- **[How to Deploy Probes on Cloudflare Containers](/guides/how-to-deploy-probes-cloudflare-containers)** - A guide for deploying private probes using Cloudflare Workers/Containers. (Example deployment guide)
42
+
- **[Monitoring Overview](/monitoring/overview)** - Conceptual overview of monitoring within OpenStatus.
43
+
- **[CLI Reference](/reference/cli-reference)** - Manage monitors as code, including those utilizing private locations.
+52
-19
apps/docs/src/content/docs/reference/status-page.mdx
+52
-19
apps/docs/src/content/docs/reference/status-page.mdx
···
1
1
---
2
-
title: Status Page
2
+
title: Status Page Reference
3
+
description: Complete technical specification for OpenStatus status page configuration.
3
4
---
4
5
5
-
A status page is a web page that displays the current status of a service or system.
6
+
## Overview
7
+
8
+
A status page is a dedicated web interface provided by OpenStatus that publicly displays the operational status of your services and systems. It serves as a transparent communication tool during incidents and for showcasing overall service health.
9
+
10
+
**Key features:**
11
+
- Real-time service status updates.
12
+
- Incident communication and history.
13
+
- Customizable branding and domain.
14
+
- Multiple access control options.
6
15
7
16
## Configuration
8
17
18
+
OpenStatus provides several configuration options to customize your status page's appearance, accessibility, and functionality.
19
+
9
20
### Slug
10
21
11
-
You slug is a unique identifier for your status page. It is used in the URL of your status page. e.g `status` => `https://status.openstatus.dev`
22
+
**Type:** String (required)
23
+
**Format:** URL-friendly string (e.g., `my-service-status`)
24
+
25
+
A unique identifier that forms part of your status page's default URL. For example, a slug of `status` will result in a URL like `https://status.openstatus.dev`.
12
26
13
27
### Custom Domain
14
28
15
-
You can configure a custom domain for your status page. e.g `status.example.com` => `https://status.example.com`
29
+
**Type:** String (optional)
30
+
**Format:** Valid domain name (e.g., `status.example.com`)
16
31
17
-
### Password (basic auth)
32
+
Allows you to host your status page on a custom domain. Once configured, your status page will be accessible at `https://your-custom-domain.com`.
18
33
19
-
You can add a password for your status page to protect a status page. If you are not authenticated, you will get redirected to the `/login`.
34
+
### Password (Basic Auth)
20
35
21
-
The password is stored in plain text in a `cookie`, so keep the password easy and fun. You can share any page by appending the password via the `pw` search param like: `https://[slug].openstatus.dev/?pw=my-secret-password` and we will automatically authenticate the user. This can be useful to authenticate to private RSS feeds.
36
+
**Type:** String (optional)
37
+
38
+
Enables basic password protection for your status page. If a password is set, users will be redirected to a login page (`/login`) to gain access. The password is stored in a cookie upon successful authentication.
39
+
40
+
**Sharing with password:** You can provide direct access by appending the password as a URL search parameter: `https://[slug].openstatus.dev/?pw=your-secret-password`. This method is also useful for authenticating private RSS feeds.
22
41
23
-
### Magic Link (session auth)
42
+
### Magic Link (Session Auth)
24
43
25
-
You can secure your status page by restricting access to users with approved email domains. Users will receive a magic link sent to their email and, upon clicking it, will be authenticated via a session token.
44
+
**Type:** Boolean (add-on feature)
26
45
27
-
This feature is available as an add-on for paid plans and is not included by default.
46
+
Restricts access to your status page to users with approved email domains. Users receive a magic link via email, which, upon clicking, authenticates them via a session token. This feature is typically available as a paid add-on for specific plans.
28
47
29
48
### Favicon
30
49
31
-
You can add a favicon for your status page.
50
+
**Type:** Image file (e.g., `.ico`, `.png`)
32
51
52
+
Allows you to upload a custom favicon that will appear in browser tabs and bookmarks for your status page.
33
53
34
-
### JSON Feed
54
+
### JSON Feed
35
55
36
-
You can access your status page data in JSON format by appending `/feed/json` to your status page URL.
56
+
**Type:** Read-only endpoint
57
+
**Format:** JSON
37
58
38
-
Example: `https://status.openstatus.dev/feed/json`
59
+
Provides a machine-readable JSON representation of your status page data. This feed can be accessed by appending `/feed/json` to your status page URL.
60
+
61
+
**Example:** `https://status.openstatus.dev/feed/json`
39
62
40
63
### SSH Command
41
64
42
-
Check the current status page anytime from your Terminal with:
65
+
**Type:** Command-line utility
66
+
67
+
Allows you to quickly check the current status page status directly from your terminal using an SSH command.
68
+
69
+
**Usage:**
43
70
44
-
```
71
+
```bash
45
72
ssh [slug]@ssh.openstatus.dev
46
73
```
47
74
48
-
Example: `ssh status@ssh.openstatus.dev`
75
+
**Example:** `ssh my-service@ssh.openstatus.dev`
49
76
50
77
### White Label
51
78
52
-
The White Label add-on allows you to remove the "powered by openstatus.dev" footer from your status page, providing a fully branded experience for your users.
79
+
**Type:** Boolean (add-on feature)
80
+
81
+
Removes the "powered by openstatus.dev" footer from your status page, providing a fully branded experience. This feature is typically available as a paid add-on for Starter and Pro plans and is enabled via your workspace settings, affecting all status pages within that workspace.
53
82
54
-
This feature is available as a paid add-on for Starter and Pro plans at $300/month. Once enabled in your workspace settings, the OpenStatus branding will be removed from all status pages in your workspace.
83
+
## Related resources
84
+
85
+
- **[Create Status Page](/status-page/create-status-page)** - Step-by-step tutorial on creating a status page.
86
+
- **[How to Configure Status Page](/tutorial/how-to-configure-status-page)** - Guide on advanced status page configuration.
87
+
- **[Status Report Reference](/reference/status-report)** - Details on how incident statuses are managed and reported.
+41
-10
apps/docs/src/content/docs/reference/status-report.mdx
+41
-10
apps/docs/src/content/docs/reference/status-report.mdx
···
1
1
---
2
-
title: Status Report
2
+
title: Status Report Reference
3
+
description: Technical specification for incident status updates within OpenStatus.
3
4
---
4
5
5
-
A status report is an event of an incident.
6
+
## Overview
6
7
8
+
A status report is a chronological update or event associated with an ongoing incident in OpenStatus. These reports are crucial for communicating the progress of an incident, from initial detection to final resolution, providing transparency to stakeholders.
7
9
8
-
## Configuration
10
+
**Purpose:**
11
+
- To document the lifecycle and progress of an incident.
12
+
- To communicate current incident status and actions taken.
13
+
- To provide historical context for post-incident analysis.
14
+
15
+
## Relationship to Incidents
16
+
17
+
Each status report is directly linked to a specific incident. As an incident progresses through its resolution process, new status reports are added to provide updates, often accompanied by a change in the incident's overall status.
18
+
19
+
## Configuration and Properties
20
+
21
+
A status report consists of several key properties that define its content and context.
9
22
10
23
### Status
11
24
12
-
The status of an incident can be:
25
+
**Type:** Enumerated String (required)
26
+
27
+
Represents the current stage or state of the associated incident at the time the report is issued. The available statuses are:
13
28
14
-
- `investigating`
15
-
- `identified`
16
-
- `monitoring`
17
-
- `resolved`
29
+
- `investigating`: The incident has been detected, and the team is actively looking into the root cause.
30
+
- `identified`: The root cause of the incident has been identified.
31
+
- `monitoring`: A fix has been deployed or a mitigation is in place, and the service is being monitored to confirm resolution.
32
+
- `resolved`: The incident has been fully resolved, and the service is operating normally.
18
33
19
34
### Date
20
35
21
-
The date of the status report
36
+
**Type:** Datetime (required)
37
+
**Format:** ISO 8601 (e.g., `2026-01-05T12:30:00Z`)
38
+
39
+
The timestamp indicating when the status report was created or when the reported status took effect. This provides a clear timeline for incident progression.
22
40
23
41
### Message
24
42
25
-
The message of the status report
43
+
**Type:** String (required)
44
+
45
+
A descriptive message detailing the update, actions taken, or any relevant information regarding the incident at the time of the report. This message should be clear and concise, providing context to the status change.
46
+
47
+
**Example Messages:**
48
+
- `"Initial detection of elevated error rates on the API. Investigating potential upstream issues."`
49
+
- `"Root cause identified as a misconfigured caching layer. Working on a rollback."`
50
+
- `"Fix deployed to production. Monitoring service health for full recovery."`
51
+
- `"All services restored to normal operation. Incident resolved."`
52
+
53
+
## Related resources
54
+
55
+
- **[Incident Reference](/reference/incident)** - Detailed information on incident creation and lifecycle.
56
+
- **[Status Page Reference](/reference/status-page)** - Information on how status reports are displayed on public status pages.
+39
-3
apps/docs/src/content/docs/reference/subscriber.mdx
+39
-3
apps/docs/src/content/docs/reference/subscriber.mdx
···
1
1
---
2
-
title: Subscriber
2
+
title: Subscriber Reference
3
+
description: Technical specification for managing status page subscribers and their notifications.
3
4
---
4
5
5
-
A subscriber is a user who receives notifications about incidents.
6
+
## Overview
7
+
8
+
A subscriber in OpenStatus is an entity (typically a user or an integration) that opts to receive real-time notifications and updates regarding incidents and status changes on a specific status page. Subscribers play a crucial role in maintaining transparent communication during service disruptions.
9
+
10
+
**Key functions of subscribers:**
11
+
- Receive automated alerts when monitor statuses change or incidents are updated.
12
+
- Stay informed about service health without actively monitoring the status page.
13
+
- Choose preferred notification channels for receiving updates.
14
+
15
+
## Subscription Process
6
16
7
-
They have to subscribe to update from your status page.
17
+
Users typically subscribe to a status page's updates through a dedicated interface provided on the status page itself. The process involves:
18
+
19
+
1. **Inputting Contact Information:** Providing an email address, phone number, or other contact details depending on the available notification channels.
20
+
2. **Opt-in Confirmation:** Confirming their subscription, often through a verification link sent to the provided contact to prevent unwanted subscriptions.
21
+
3. **Channel Selection (Optional):** Selecting which specific notification channels (e.g., email, SMS, Slack webhook) they wish to receive updates through, if multiple options are available.
22
+
23
+
## Notification Types Received
24
+
25
+
Subscribers receive notifications for key events affecting the monitored services linked to the status page:
26
+
27
+
- **Incident Creation:** When a new incident is detected and published.
28
+
- **Incident Updates:** When status reports are published for an ongoing incident (e.g., status changes from `investigating` to `identified`, `monitoring`, or `resolved`).
29
+
- **Monitor Status Changes:** Direct alerts for individual monitor status changes if configured to do so (less common for public subscribers).
30
+
31
+
## Subscriber Management
32
+
33
+
Status page administrators can manage their subscriber lists, including:
34
+
35
+
- **Viewing Subscribers:** Accessing a list of all active subscribers for a status page.
36
+
- **Adding/Removing Subscribers:** Manually adding or removing subscribers.
37
+
- **Communication:** Sending ad-hoc notifications to the subscriber list (if supported by the platform).
38
+
39
+
## Related resources
40
+
41
+
- **[Status Page Reference](/reference/status-page)** - Detailed information on managing and configuring status pages.
42
+
- **[Notification Channels Reference](/reference/notification)** - Technical specifications for the various notification delivery methods.
43
+
- **[Incident Reference](/reference/incident)** - Information about incident creation and management.
+75
-17
apps/docs/src/content/docs/reference/tcp-monitor.mdx
+75
-17
apps/docs/src/content/docs/reference/tcp-monitor.mdx
···
1
1
---
2
-
title: TCP Monitor
2
+
title: TCP Monitor Reference
3
+
description: Complete technical specification for TCP service monitoring.
3
4
---
4
5
6
+
## Overview
5
7
6
-
A TCP Monitor is a component that allows you to monitor the status of your services.
8
+
A TCP Monitor is a component that establishes a connection to a specified TCP endpoint (IP address and port) to verify its reachability and responsiveness. This is fundamental for monitoring the availability of services that communicate over TCP, such as databases, mail servers, and custom network services.
9
+
10
+
**Use cases:**
11
+
- Database server availability checks (e.g., PostgreSQL, MySQL).
12
+
- Mail server (SMTP, IMAP, POP3) reachability.
13
+
- Custom application service port monitoring.
14
+
- Validating network connectivity to specific endpoints.
7
15
8
16
## Configuration
9
17
10
18
### URI
11
19
12
-
The url of the endpoint you want to monitor e.g `openstat.us:443`
20
+
**Type:** String (required)
21
+
**Format:** Hostname or IP address with port (e.g., `example.com:8080`, `192.168.1.1:22`)
22
+
23
+
The endpoint of the TCP service you want to monitor. This includes the hostname or IP address and the port number.
24
+
25
+
**Examples:**
26
+
- `openstat.us:443`
27
+
- `db.internal:5432`
28
+
- `10.0.0.5:3306`
13
29
14
30
### Regions
15
31
16
-
The regions where we are triggering the HTTP request.
32
+
**Type:** Array of Strings (required)
33
+
**Format:** Region identifiers (e.g., `iad`, `jnb`)
34
+
35
+
The geographical regions from which the TCP connection attempt will be initiated. This allows for verification of service availability and network latency across different global locations.
17
36
18
37
__Africa__
19
38
···
69
88
70
89
### Frequency
71
90
72
-
The check interval, we support the following frequencies:
73
-
- 30 seconds
74
-
- 1 minute
75
-
- 5 minutes
76
-
- 10 minutes
77
-
- 30 minutes
78
-
- 1 hour
91
+
**Type:** String (required)
92
+
**Format:** Duration string (e.g., `30s`, `1m`, `1h`)
93
+
94
+
The interval at which the TCP monitor will attempt to connect to the target URI. Supported frequencies:
95
+
- `30 seconds`
96
+
- `1 minute`
97
+
- `5 minutes`
98
+
- `10 minutes`
99
+
- `30 minutes`
100
+
- `1 hour`
79
101
80
102
### Response Time Thresholds
103
+
81
104
#### Timeout
82
-
The timeout for the HTTP request, default: `45 seconds`
105
+
106
+
**Type:** Duration (optional)
107
+
**Default:** `45 seconds`
108
+
109
+
The maximum duration to wait for a successful TCP connection. If the connection cannot be established within this time, the check is considered a failure.
110
+
83
111
#### Degraded
84
-
The duration for which the HTTP request is considered degraded.
112
+
113
+
**Type:** Duration (optional)
114
+
115
+
The duration after which a TCP connection attempt is considered to be in a degraded performance state. This allows for early warning of network latency or service slowdowns.
85
116
86
117
### Retry
87
-
The number of retries for the HTTP request. Default: `3`
118
+
119
+
**Type:** Integer (optional)
120
+
**Default:** `3`
121
+
122
+
The number of times the monitor will automatically retry a failed TCP connection attempt before reporting a definitive error. For example: `3`
88
123
89
124
### OpenTelemetry
90
-
#### OTPL Endpoint
91
-
The endpoint we use to export the metrics. We only support HTTP endpoint.
125
+
126
+
Configures the export of monitoring metrics to an OpenTelemetry-compatible observability platform.
127
+
128
+
#### OTLP Endpoint
129
+
130
+
**Type:** String (optional)
131
+
**Protocol:** HTTP only
132
+
133
+
The OTLP (OpenTelemetry Protocol) endpoint URL where collected metrics should be exported. Only HTTP endpoints are supported for metric export.
134
+
92
135
#### OTLP Headers
93
-
The headers we use to export the metrics to your otlp endpoint.
136
+
137
+
**Type:** Key-value pairs (optional)
138
+
139
+
Custom headers to include when sending metrics to your OTLP endpoint. Commonly used for authentication or tenant identification.
140
+
141
+
**Common example:**
142
+
```
143
+
Authorization: Bearer <your_token>
144
+
```
145
+
146
+
## Related resources
147
+
148
+
- **[Create Your First Monitor](/tutorial/how-to-create-monitor)** - Step-by-step tutorial on setting up a monitor.
149
+
- **[Monitoring Overview](/monitoring/overview)** - Conceptual overview of OpenStatus monitoring capabilities.
150
+
- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - Detailed information on all metrics and data points collected by monitors.
151
+
- **[CLI Reference](/reference/cli-reference)** - Guide to managing OpenStatus monitors programmatically using the command-line interface.
+115
-15
apps/docs/src/content/docs/reference/terraform.mdx
+115
-15
apps/docs/src/content/docs/reference/terraform.mdx
···
1
1
---
2
-
title: Terraform Provider
3
-
description:
4
-
"Use OpenStatus Terraform provider to manage your monitors and status page."
2
+
title: Terraform Provider Reference
3
+
description: Technical specification for the OpenStatus Terraform Provider.
5
4
---
6
5
7
-
Here you can find the official OpenStatus Terraform provider. This provider
8
-
allows you to manage your monitors and status page using Terraform.
6
+
## Overview
7
+
8
+
The OpenStatus Terraform provider enables you to manage your OpenStatus monitors and status pages programmatically using HashiCorp Terraform. This allows for Infrastructure as Code (IaC) practices, version control, and automated deployment of your monitoring configurations.
9
+
10
+
**Key capabilities:**
11
+
- Define and manage OpenStatus monitors as Terraform resources.
12
+
- Automate the deployment and updates of monitoring configurations.
13
+
- Integrate OpenStatus into your existing IaC workflows.
9
14
10
-
https://registry.terraform.io/providers/openstatusHQ/openstatus/latest
15
+
## Installation
11
16
12
-
## Usage
17
+
To use the OpenStatus Terraform provider, declare it in your Terraform configuration file (`.tf`). Terraform will automatically download and install the provider when you run `terraform init`.
13
18
19
+
```terraform
20
+
terraform {
21
+
required_providers {
22
+
openstatus = {
23
+
source = "openstatusHQ/openstatus"
24
+
version = "~> 0.1" # Use the latest version
25
+
}
26
+
}
27
+
}
14
28
```
29
+
30
+
For the latest provider version, refer to the [official Terraform Registry](https://registry.terraform.io/providers/openstatusHQ/openstatus/latest).
31
+
32
+
## Provider Configuration
33
+
34
+
The OpenStatus Terraform provider requires authentication via an API token.
35
+
36
+
### `openstatus_api_token`
37
+
38
+
**Type:** String (required)
39
+
**Description:** Your OpenStatus API Access Token. This token is used to authenticate your Terraform requests with the OpenStatus API.
40
+
41
+
**Example:**
42
+
43
+
```terraform
15
44
provider "openstatus" {
16
-
openstatus_api_token= "YOUR_API_TOKEN"
45
+
openstatus_api_token = "YOUR_OPENSTATUS_API_TOKEN"
17
46
}
47
+
```
18
48
19
-
resource "openstatus_monitor" "my_monitor" {
20
-
url = "https://www.openstatus.dev"
21
-
regions= ["iad", "jnb"]
22
-
periodicity = "10m"
23
-
name = "test-monitor"
24
-
active = true
25
-
description = "This is a test monitor"
49
+
## Resources
50
+
51
+
The provider currently supports managing `openstatus_monitor` resources.
52
+
53
+
### `openstatus_monitor`
54
+
55
+
Manages an OpenStatus monitor. This resource allows you to define and control the parameters of a synthetic monitor.
56
+
57
+
**Arguments:**
58
+
59
+
| Argument | Type | Required | Default | Description |
60
+
| :------------ | :-------------------- | :------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------- |
61
+
| `url` | `string` | Yes | | The URL or URI of the endpoint to be monitored. Format depends on the monitor type (e.g., full URL for HTTP, host:port for TCP). |
62
+
| `regions` | `list(string)` | Yes | | A list of region identifiers (e.g., `"iad"`, `"jnb"`) from where the monitor checks will be performed. |
63
+
| `periodicity` | `string` | Yes | | The frequency at which the monitor will perform checks. Supported values: `"30s"`, `"1m"`, `"5m"`, `"10m"`, `"30m"`, `"1h"`. |
64
+
| `name` | `string` | Yes | | A human-readable name for the monitor. |
65
+
| `active` | `bool` | Yes | | Specifies whether the monitor is active (`true`) or paused (`false`). |
66
+
| `description` | `string` (optional) | No | `""` | A detailed description of the monitor's purpose or configuration. |
67
+
| `monitor_type` | `string` | Yes | | The type of monitor to create. Supported values: `"HTTP"`, `"TCP"`, `"DNS"` |
68
+
| `method` | `string` (optional) | No | `"GET"` | (HTTP monitors only) The HTTP method to use for the request (e.g., `"GET"`, `"POST"`). |
69
+
| `body` | `string` (optional) | No | `""` | (HTTP monitors only) The request body to send for `POST`, `PUT`, `PATCH` methods. |
70
+
| `headers` | `map(string)` (optional)| No | `{}` | (HTTP monitors only) A map of custom HTTP headers to include with the request. |
71
+
| `timeout` | `string` (optional) | No | `"45s"` | The maximum duration to wait for a response. Format: duration string (e.g., `"30s"`, `"1m"`). |
72
+
| `degraded_after`| `string` (optional) | No | `""` | The duration after which a response is considered degraded. Format: duration string. |
73
+
| `retries` | `number` (optional) | No | `3` | The number of times the monitor will retry a failed check. |
74
+
| `public` | `bool` (optional) | No | `false` | Controls whether monitor data is accessible on your public status page. |
75
+
| `otlp_endpoint`| `string` (optional) | No | `""` | The OTLP (OpenTelemetry Protocol) endpoint URL for exporting metrics. |
76
+
| `otlp_headers`| `map(string)` (optional)| No | `{}` | Custom headers to include when exporting metrics to your OTLP endpoint. |
77
+
78
+
**Example Usage:**
79
+
80
+
```terraform
81
+
resource "openstatus_monitor" "my_website_monitor" {
82
+
name = "My Website Availability"
83
+
description = "Checks the main website for uptime and response time."
84
+
url = "https://www.example.com"
85
+
monitor_type = "HTTP"
86
+
method = "GET"
87
+
regions = ["us-east-1", "eu-west-1"]
88
+
periodicity = "1m"
89
+
active = true
90
+
public = true
91
+
timeout = "60s"
92
+
}
93
+
94
+
resource "openstatus_monitor" "internal_api_monitor" {
95
+
name = "Internal API Health Check"
96
+
description = "Monitors the health of a critical internal API."
97
+
url = "https://api.internal.corp:8443/health"
98
+
monitor_type = "HTTP"
99
+
method = "GET"
100
+
regions = ["private-location-id"]
101
+
periodicity = "5m"
102
+
active = true
103
+
public = false
104
+
headers = {
105
+
"Authorization" = "Bearer ${var.internal_api_token}"
106
+
"Accept" = "application/json"
107
+
}
108
+
}
109
+
110
+
resource "openstatus_monitor" "database_port_monitor" {
111
+
name = "Database TCP Port Check"
112
+
description = "Ensures the PostgreSQL port is open and reachable."
113
+
url = "db.example.com:5432"
114
+
monitor_type = "TCP"
115
+
regions = ["us-west-2"]
116
+
periodicity = "30s"
117
+
active = true
26
118
}
27
119
```
120
+
121
+
## Related resources
122
+
123
+
- **[OpenStatus Monitoring Overview](/monitoring/overview)** - Learn more about monitoring concepts in OpenStatus.
124
+
- **[HTTP Monitor Reference](/reference/http-monitor)** - Detailed specification for HTTP monitor configuration.
125
+
- **[TCP Monitor Reference](/reference/tcp-monitor)** - Detailed specification for TCP monitor configuration.
126
+
- **[DNS Monitor Reference](/reference/dns-monitor)** - Detailed specification for DNS monitor configuration.
127
+
- **[CLI Reference](/reference/cli-reference)** - Manage monitors using the OpenStatus command-line interface.
-35
apps/docs/src/content/docs/status-page/advanced/badge.mdx
-35
apps/docs/src/content/docs/status-page/advanced/badge.mdx
···
1
-
---
2
-
title: Badge
3
-
description: "How to embed the status page badge on your website or GitHub README"
4
-
---
5
-
6
-
You can embed the status page badge on your website or GitHub README to show the
7
-
current status of your services.
8
-
9
-
<a href="https://status.openstatus.dev">
10
-
<img src="https://status.openstatus.dev/badge" />
11
-
</a>
12
-
13
-
Copy the following code and paste it into your website or GitHub README:
14
-
15
-
```html
16
-
<img src="https://YOUR-SLUG.openstatus.dev/badge" />
17
-
```
18
-
19
-
If you want the dark version of the badge, you can use the following URL:
20
-
21
-
```html
22
-
<img src="https://YOUR-SLUG.openstatus.dev/badge?theme=dark" />
23
-
```
24
-
25
-
You can also customize the size of the badge by adding a `size` parameter:
26
-
27
-
- `sm`
28
-
- `md`
29
-
- `lg`
30
-
- `xl`
31
-
32
-
33
-
```html
34
-
<img src="https://YOUR-SLUG.openstatus.dev/badge?theme=dark&size=xl" />
35
-
```
+2
-2
apps/docs/src/content/docs/status-page/advanced/custom-domain.mdx
+2
-2
apps/docs/src/content/docs/status-page/advanced/custom-domain.mdx
···
1
1
---
2
2
title: Custom Domain
3
-
description: "How to connect a custom domain to your status page in OpenStatus"
3
+
description: "How to connect a custom domain to your status page in openstatus"
4
4
---
5
5
6
6
import { Aside } from '@astrojs/starlight/components';
···
9
9
10
10
To connect a custom domain to your status page: _Select a status page → Domain →_.
11
11
12
-
You will be asked to enter your custom domain. And we will provide you with a DNS record to add to your domain provider.
12
+
You will be asked to enter your custom domain. And we will provide you with a DNS record to add to your domain provider.
+2
-3
apps/docs/src/content/docs/status-page/advanced/description.mdx
+2
-3
apps/docs/src/content/docs/status-page/advanced/description.mdx
···
1
1
---
2
2
title: Description
3
-
description: "How to set a custom description for your status page in OpenStatus"
3
+
description: "How to set a custom description for your status page in openstatus"
4
4
---
5
5
6
6
import { Image } from 'astro:assets';
···
17
17
18
18
<Image
19
19
src={StatusPage}
20
-
alt="OpenStatus status page"
20
+
alt="openstatus status page"
21
21
/>
22
-
+2
-2
apps/docs/src/content/docs/status-page/advanced/icon.mdx
+2
-2
apps/docs/src/content/docs/status-page/advanced/icon.mdx
···
1
1
---
2
2
title: Icon
3
-
description: "How to set a custom icon for your status page in OpenStatus"
3
+
description: "How to set a custom icon for your status page in openstatus"
4
4
---
5
5
6
6
import { Image } from 'astro:assets';
···
16
16
17
17
<Image
18
18
src={StatusPage}
19
-
alt="OpenStatus status page"
19
+
alt="openstatus status page"
20
20
/>
+2
-2
apps/docs/src/content/docs/status-page/advanced/monitors.mdx
+2
-2
apps/docs/src/content/docs/status-page/advanced/monitors.mdx
···
1
1
---
2
2
title: Monitors
3
-
description: "How to connect your monitors for your status page in OpenStatus"
3
+
description: "How to connect your monitors for your status page in openstatus"
4
4
---
5
5
6
6
Connect your created monitors to your status page to display the current status of your services.
···
21
21
22
22
To make a monitor public: _Select a monitor → Settings → Danger → Toggle Public monitor.
23
23
24
-
You can see an example of a public monitor at [https://status.openstatus.dev/monitors/1](https://status.openstatus.dev/monitors/1).
24
+
You can see an example of a public monitor at [https://status.openstatus.dev/monitors/1](https://status.openstatus.dev/monitors/1).
+1
-2
apps/docs/src/content/docs/status-page/advanced/password.mdx
+1
-2
apps/docs/src/content/docs/status-page/advanced/password.mdx
···
1
1
---
2
2
title: Password protection
3
-
description: "How to password protect your status page in OpenStatus"
3
+
description: "How to password protect your status page in openstatus"
4
4
---
5
5
6
6
import { Aside } from '@astrojs/starlight/components';
···
12
12
To change toggle the protection or change password of your status page: _Select a status page → Settings → Visibility_.
13
13
14
14
The password is stored stored unencrypted in our database and can be shared via `password` search param in the URL, e.g. `https://statuspage.openstatus.dev?password=top-secret`. We recommend using a unique password for your status page.
15
-
-175
apps/docs/src/content/docs/status-page/advanced/widget.mdx
-175
apps/docs/src/content/docs/status-page/advanced/widget.mdx
···
1
-
---
2
-
title: Public Status Widget
3
-
description: "How to embed the public status widget in your React application"
4
-
---
5
-
import { Aside } from '@astrojs/starlight/components';
6
-
7
-
import { Image } from 'astro:assets';
8
-
9
-
import Widget from '../../../../assets/status-widget/widget-example.png';
10
-
11
-
12
-
13
-
We have added a public endpoint where you can access the status of your status
14
-
page. To access it, you only need the unique `:slug` you have chosen for your
15
-
page.
16
-
17
-
```bash
18
-
curl https://api.openstatus.dev/public/status/:slug
19
-
```
20
-
21
-
<Aside>
22
-
We have released an `@openstatus/react` npm package that allows you to easily
23
-
integrate the pre-typed status into your React projects or use the default
24
-
widget. Read more [here](/tools/react).
25
-
</Aside>
26
-
27
-
The response is a JSON object with the following structure:
28
-
29
-
```json
30
-
{ "status": "operational" }
31
-
```
32
-
33
-
in which the status can be one of the following values:
34
-
35
-
```ts
36
-
enum Status {
37
-
Operational = "operational",
38
-
DegradedPerformance = "degraded_performance",
39
-
PartialOutage = "partial_outage",
40
-
MajorOutage = "major_outage",
41
-
UnderMaintenance = "under_maintenance", // currently not in use
42
-
Unknown = "unknown",
43
-
Incident = "incident",
44
-
}
45
-
```
46
-
47
-
### How does it work?
48
-
49
-
The status is calculated by the ratio `uptime / (uptime + downtime)` of the last
50
-
5 cron jobs of each monitor which we accumulate together. It is a simple
51
-
calculation that gives us a good overview of the status of your services.
52
-
53
-
```ts
54
-
function getStatus(ratio: number) {
55
-
if (isNaN(ratio)) return Status.Unknown;
56
-
if (ratio >= 0.98) return Status.Operational;
57
-
if (ratio >= 0.6) return Status.DegradedPerformance;
58
-
if (ratio >= 0.3) return Status.PartialOutage;
59
-
if (ratio >= 0) return Status.MajorOutage;
60
-
return Status.Unknown;
61
-
}
62
-
```
63
-
64
-
We are caching the result for `30 seconds` to reduce the load on our database.
65
-
66
-
The `Status.Incident` will always be returned when then status of any incident
67
-
on your page is **not** _"monitoring"_ or _"resolved"_. You can attach an
68
-
incident to a monitor (implicit) or a page (explicit).
69
-
70
-
> If you have a doubt about the above calculation, feel free to contact us via
71
-
> [ping@openstatus.dev](mailto:ping@openstatus.dev) or
72
-
> [discord](https://openstatus.dev/discord).
73
-
74
-
### React Widget
75
-
76
-
We currently do not provide any SDK or package to integrate the status into your
77
-
stack. But will in the future.
78
-
79
-
If you are using Nextjs and RSC with the `/app` directory, feel free to use that
80
-
Component. Small reminder that we are using shadcn ui and tailwindcss. You might
81
-
want to update the `bg-muted` and `text-foreground` classes to your needs.
82
-
83
-
84
-
<Image
85
-
src={Widget}
86
-
alt="Status Widget"
87
-
/>
88
-
89
-
90
-
91
-
We are using `zod` to validate the response. You can use any other library if
92
-
you want or just remove it. But better be safe than sorry.
93
-
94
-
```tsx
95
-
import * as z from "zod";
96
-
97
-
const statusEnum = z.enum([
98
-
"operational",
99
-
"degraded_performance",
100
-
"partial_outage",
101
-
"major_outage",
102
-
"under_maintenance",
103
-
"unknown",
104
-
"incident",
105
-
]);
106
-
107
-
const statusSchema = z.object({ status: statusEnum });
108
-
109
-
const dictionary = {
110
-
operational: {
111
-
label: "Operational",
112
-
color: "bg-green-500",
113
-
},
114
-
degraded_performance: {
115
-
label: "Degraded Performance",
116
-
color: "bg-yellow-500",
117
-
},
118
-
partial_outage: {
119
-
label: "Partial Outage",
120
-
color: "bg-yellow-500",
121
-
},
122
-
major_outage: {
123
-
label: "Major Outage",
124
-
color: "bg-red-500",
125
-
},
126
-
unknown: {
127
-
label: "Unknown",
128
-
color: "bg-gray-500",
129
-
},
130
-
incident: {
131
-
label: "Incident",
132
-
color: "bg-yellow-500",
133
-
},
134
-
under_maintenance: {
135
-
label: "Under Maintenance",
136
-
color: "bg-gray-500",
137
-
},
138
-
} as const;
139
-
140
-
export async function StatusWidget({ slug }: { slug: string }) {
141
-
const res = await fetch(`https://api.openstatus.dev/public/status/${slug}`, {
142
-
next: { revalidate: 60 }, // cache request for 60 seconds
143
-
});
144
-
const data = await res.json();
145
-
const parsed = statusSchema.safeParse(data);
146
-
147
-
if (!parsed.success) {
148
-
return null;
149
-
}
150
-
151
-
const key = parsed.data.status;
152
-
const { label, color } = dictionary[key];
153
-
154
-
return (
155
-
<a
156
-
className="border-border text-foreground/70 hover:bg-muted hover:text-foreground inline-flex max-w-fit items-center gap-2 rounded-md border px-3 py-1 text-sm"
157
-
href={`https://${slug}.openstatus.dev`}
158
-
target="_blank"
159
-
rel="noreferrer"
160
-
>
161
-
{label}
162
-
<span className="relative flex h-2 w-2">
163
-
{parsed.data.status === "operational" ? (
164
-
<span
165
-
className={`absolute inline-flex h-full w-full animate-ping rounded-full ${color} opacity-75 duration-1000`}
166
-
/>
167
-
) : null}
168
-
<span
169
-
className={`relative inline-flex h-2 w-2 rounded-full ${color}`}
170
-
/>
171
-
</span>
172
-
</a>
173
-
);
174
-
}
175
-
```
+3
-4
apps/docs/src/content/docs/status-page/overview.mdx
+3
-4
apps/docs/src/content/docs/status-page/overview.mdx
···
1
1
---
2
2
title: Status page
3
-
description: "Discover what is a status page in OpenStatus"
3
+
description: "Discover what is a status page in openstatus"
4
4
---
5
5
import { Image } from 'astro:assets';
6
6
···
8
8
9
9
<Image
10
10
src={StatusPage}
11
-
alt="OpenStatus status page"
11
+
alt="openstatus status page"
12
12
/>
13
13
14
14
···
19
19
services. It shows the current status of your services and the history of
20
20
incidents.
21
21
22
-
You can create a status page with OpenStatus and display the status of your synthetic checks.
22
+
You can create a status page with openstatus and display the status of your synthetic checks.
23
23
24
24
You can see our own status page at [https://status.openstatus.dev](https://status.openstatus.dev).
25
-
+2
-2
apps/docs/src/content/docs/tools/terraform.mdx
+2
-2
apps/docs/src/content/docs/tools/terraform.mdx
···
1
1
---
2
2
title: Terraform Provider
3
3
description:
4
-
"Use OpenStatus Terraform provider to manage your monitors and status page."
4
+
"Use openstatus Terraform provider to manage your monitors and status page."
5
5
---
6
6
7
-
Here you can find the official OpenStatus Terraform provider. This provider
7
+
Here you can find the official openstatus Terraform provider. This provider
8
8
allows you to manage your monitors and status page using Terraform.
9
9
10
10
https://registry.terraform.io/providers/openstatusHQ/openstatus/latest
+69
-10
apps/docs/src/content/docs/tutorial/get-started-with-openstatus-cli.mdx
+69
-10
apps/docs/src/content/docs/tutorial/get-started-with-openstatus-cli.mdx
···
1
1
---
2
2
title: Get Started with openstatus CLI
3
+
description: "Step-by-step tutorial to install and use the openstatus CLI for monitoring as code"
3
4
---
4
5
5
6
import { Image } from 'astro:assets';
6
7
import CLI from '../../../assets/tutorial/get-started-with-openstatus-cli/CLI.png';
7
8
9
+
## What you'll learn
10
+
11
+
In this tutorial, you'll learn how to use the openstatus CLI to manage your monitors as code. This enables you to version control your monitoring configuration, automate deployments, and implement GitOps workflows.
12
+
13
+
### Prerequisites
14
+
15
+
- An openstatus account
16
+
- Command line experience
17
+
- API token from your openstatus workspace (Settings → API)
18
+
19
+
### What you'll build
20
+
21
+
By the end of this tutorial, you'll have:
22
+
- openstatus CLI installed on your system
23
+
- Monitors exported to a YAML configuration file
24
+
- Understanding of monitoring as code workflows
25
+
- Ability to manage monitors programmatically
26
+
8
27
<Image
9
28
src={CLI}
10
-
alt="openstatus CLI"
29
+
alt="openstatus CLI in action showing monitor management"
11
30
/>
12
31
13
32
## Installation
14
33
34
+
Install the openstatus CLI to manage your monitors directly from code.
15
35
16
-
Install the OpenStatus CLI to set up your monitors straight in your code.
36
+
### macOS
17
37
18
-
### OS X
38
+
Using Homebrew (recommended):
19
39
```bash
20
40
brew install openstatusHQ/cli/openstatus --cask
21
41
```
22
-
or
23
42
43
+
Or using the install script:
24
44
```bash
25
45
curl -sSL instl.sh/openstatushq/cli/macos | bash
26
46
```
27
47
28
48
### Linux
49
+
29
50
```bash
30
51
curl -sSL instl.sh/openstatushq/cli/linux | bash
31
52
```
···
36
57
iwr instl.sh/openstatushq/cli/windows | iex
37
58
```
38
59
39
-
## Add API Key
60
+
## Configure API authentication
40
61
41
-
Create an API key in your workspace settings.
62
+
Create an API key in your workspace settings (Settings → API), then set it as an environment variable:
42
63
43
64
```bash
44
65
export OPENSTATUS_API_TOKEN=<your-api-token>
45
66
```
46
67
47
-
## Import Monitors
68
+
**Tip**: Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) to persist across sessions.
48
69
49
-
Import monitors from your workspace to a YAML file.
70
+
## Import existing monitors
71
+
72
+
Start by importing your existing monitors from your workspace to a YAML file:
50
73
51
74
```bash
52
75
openstatus monitors import
53
76
```
54
77
55
-
### Manage Monitors
78
+
This creates an `openstatus.yaml` file containing all your current monitors. This file becomes your single source of truth for monitoring configuration.
79
+
80
+
## Manage monitors as code
56
81
57
-
Add, remove, or update monitors from a YAML file and apply your changes.
82
+
Now you can add, remove, or update monitors in the YAML file and apply your changes:
58
83
59
84
```bash
60
85
openstatus monitors apply
61
86
```
87
+
88
+
The CLI will show you a diff of changes before applying them, ensuring you're aware of what will be modified.
89
+
90
+
## What you've accomplished
91
+
92
+
Excellent work! You've successfully:
93
+
- ✅ Installed the openstatus CLI
94
+
- ✅ Configured API authentication
95
+
- ✅ Imported monitors to a YAML file
96
+
- ✅ Learned the monitoring as code workflow
97
+
98
+
## What's next?
99
+
100
+
Now that you have the CLI set up, you can:
101
+
102
+
- **[Monitor Your MCP Server](/guides/how-to-monitor-mcp-server/)** - Example of CLI-based monitor configuration
103
+
- **[Monitoring as Code](/monitoring/monitoring-as-code)** - Learn about the YAML configuration format
104
+
- **[CLI Reference](/reference/cli-reference)** - Complete command documentation
105
+
- **[Set up CI/CD](/guides/how-to-run-synthetic-test-github-action/)** - Automate monitoring in your pipeline
106
+
107
+
### Advanced workflows
108
+
109
+
With the CLI, you can:
110
+
- Version control your monitoring configuration with Git
111
+
- Review monitoring changes in pull requests
112
+
- Automate monitor creation for new services
113
+
- Sync monitors across multiple environments
114
+
- Implement GitOps for infrastructure monitoring
115
+
116
+
## Learn more
117
+
118
+
- **[Monitoring as Code Concept](/concept/uptime-monitoring-as-code)** - Why manage monitors as code
119
+
- **[CLI Reference](/reference/cli-reference)** - All available commands
120
+
- **[YAML Configuration Examples](https://github.com/openstatusHQ/cli-template)** - Sample configurations
+35
-7
apps/docs/src/content/docs/tutorial/getting-started.mdx
+35
-7
apps/docs/src/content/docs/tutorial/getting-started.mdx
···
1
1
---
2
-
title: Getting Started
2
+
title: Getting Started with Tutorials
3
+
description: Step-by-step lessons to learn openstatus from the ground up
4
+
sidebar:
5
+
label: Getting Started
6
+
order: 1
3
7
---
4
8
5
-
Here are some tutorials to help you get started with OpenStatus:
9
+
## 📚 Tutorials
10
+
11
+
### What you'll learn
12
+
13
+
Our tutorials are designed to help you:
14
+
- Get your first monitor up and running
15
+
- Create and configure status pages
16
+
- Set up monitoring infrastructure
17
+
- Use openstatus CLI for automation
6
18
7
-
- [How to create your first monitor with OpenStatus](/tutorial/how-to-create-monitor)
8
-
- [How to create a status page?](/tutorial/how-to-create-status-page)
9
-
- [How to configure a status page?](/tutorial/how-to-configure-status-page)
10
-
- [How to create a private location? (beta)](/tutorial/how-to-create-private-location)
11
-
- [Get Started with openstatus CLI](/tutorial/get-started-with-openstatus-cli)
19
+
### Core Tutorials
20
+
21
+
Start your journey with openstatus:
22
+
23
+
- **[Create Your First Monitor](/tutorial/how-to-create-monitor)** - Learn the fundamentals by setting up uptime monitoring for your first endpoint
24
+
- **[Create a Status Page](/tutorial/how-to-create-status-page)** - Build a public status page to communicate service health to your users
25
+
- **[Configure Your Status Page](/tutorial/how-to-configure-status-page)** - Customize your status page with monitors, domains, and protection
26
+
27
+
### Advanced Tutorials
28
+
29
+
Once you're comfortable with the basics:
30
+
31
+
- **[Create a Private Location (Beta)](/tutorial/how-to-create-private-location)** - Set up monitoring from your own infrastructure
32
+
- **[Get Started with openstatus CLI](/tutorial/get-started-with-openstatus-cli)** - Automate monitor management with our command-line tool
33
+
34
+
### What's next?
35
+
36
+
After completing these tutorials, you'll be ready to:
37
+
- Explore [how-to guides](/guides/getting-started/) for specific tasks and advanced scenarios
38
+
- Dive into [explanations](/concept/getting-started/) to understand the concepts behind the features
39
+
- Reference our [technical documentation](/reference) for detailed specifications
+47
-5
apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdx
+47
-5
apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdx
···
1
1
---
2
-
title: How to configure a status page?
3
-
description: "How to configure a status page"
2
+
title: Configure Your Status Page
3
+
description: "A step-by-step tutorial to customize and configure your status page"
4
4
---
5
5
6
6
import { Image } from 'astro:assets';
···
14
14
import StatusPageBeta3 from '../../../assets/tutorial/configure-status-page/status-page-beta-3.png';
15
15
import StatusPageBeta4 from '../../../assets/tutorial/configure-status-page/status-page-beta-4.png';
16
16
17
-
We are releasing a new version of our status pages.
17
+
## What you'll learn
18
+
19
+
In this tutorial, you'll learn how to customize your status page's appearance and behavior. You'll explore different display options, themes, and configuration settings to create a status page that matches your brand and communication style.
18
20
19
-
Explore the themes: [https://themes.openstatus.dev](https://themes.openstatus.dev)
21
+
### Prerequisites
22
+
23
+
- An openstatus account
24
+
- A status page already created (see [Create a Status Page](/tutorial/how-to-create-status-page))
25
+
- At least one monitor added to your status page
26
+
27
+
### What you'll build
28
+
29
+
By the end of this tutorial, you'll have:
30
+
- A customized status page with your preferred theme
31
+
- Configured status trackers displaying data your way
32
+
- Links to important resources
33
+
- Preview and live configuration experience
34
+
35
+
## Status Page Redesign (Beta)
36
+
37
+
We are releasing a new version of our status pages with enhanced customization options.
38
+
39
+
Explore available themes: [https://themes.openstatus.dev](https://themes.openstatus.dev)
20
40
21
41
## Get started
22
42
···
101
121
102
122
**Contact URL**: If filled out, you will see a `Message` icon that users can click to forward them to a contact page. This can also be an email client by starting the input with `mailto:` (e.g. `mailto:support@openstatus.dev`).
103
123
104
-
105
124
---
106
125
107
126
We are adding some additional features. Feel free to let us know what's missing!
127
+
128
+
## What you've accomplished
129
+
130
+
Excellent work! You've successfully:
131
+
- ✅ Enabled and configured the new status page design (beta)
132
+
- ✅ Customized status tracker display options
133
+
- ✅ Explored and applied theme settings
134
+
- ✅ Added navigation links to your status page
135
+
- ✅ Previewed changes before making them live
136
+
137
+
## What's next?
138
+
139
+
Now that your status page is configured, you can:
140
+
141
+
- **[Configure Notifications](/monitoring/customization/notification)** - Alert your team when issues occur
142
+
- **[Best Practices for Status Pages](/concept/best-practices-status-page)** - Learn effective incident communication
143
+
- **[Add Status Subscribers](/reference/subscriber)** - Let users subscribe to updates
144
+
145
+
### Learn more
146
+
147
+
- **[Status Page Reference](/reference/status-page)** - Complete configuration options
148
+
- **[Uptime Calculation Values](/concept/uptime-calculation-and-values)** - How uptime percentages work
149
+
- **[See Examples](https://www.openstatus.dev/showcase)** - Browse other status pages for inspiration
108
150
109
151
## Video Tutorial
110
152
+38
-3
apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx
+38
-3
apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx
···
1
1
---
2
2
title: Create Your First Monitor
3
-
description: "How to create your first monitor with OpenStatus"
3
+
description: "A step-by-step tutorial to create your first monitor with openstatus"
4
4
---
5
5
6
6
import { Image } from 'astro:assets';
···
11
11
12
12
import { ShowcaseYouTube } from 'starlight-showcases'
13
13
14
+
## What you'll learn
14
15
16
+
In this tutorial, you'll learn how to create your first monitor an automated watchdog for your services. A monitor periodically checks your endpoints to ensure they are available, performant, and returning the correct data. Think of it as a `curl` command that runs 24/7, providing continuous insights into the health of your application.
15
17
16
-
This tutorial will walk you through the process of creating your first monitor, your automated watchdog for your services. A monitor periodically checks your endpoints to ensure they are available, performant, and returning the correct data. Think of it as a `curl` command that runs 24/7, providing continuous insights into the health of your application.
18
+
### Prerequisites
19
+
20
+
- An openstatus account (free tier available at [openstatus.dev](https://www.openstatus.dev))
21
+
- A URL endpoint to monitor (can be your own service or any public URL)
22
+
23
+
### What you'll build
24
+
25
+
By the end of this tutorial, you'll have:
26
+
- A working uptime monitor checking your endpoint every minute
27
+
- Real-time metrics showing response time and status codes
28
+
- Understanding of how to customize HTTP requests for different scenarios
17
29
18
30
19
31
## Get Started in 1 Minute
···
85
97
- **Simulating Clients:** Adding a User-Agent header to simulate traffic from a specific browser or device.
86
98
87
99
Heads Up: We've got your User-Agent covered!
88
-
OpenStatus automatically includes the `"User-Agent": "OpenStatus/1.0"` header in every request. This makes it easy to identify and filter out our monitoring traffic from your server logs or analytics.
100
+
openstatus automatically includes the `"User-Agent": "openstatus/1.0"` header in every request. This makes it easy to identify and filter out our monitoring traffic from your server logs or analytics.
89
101
90
102
91
103
···
93
105
## Important Considerations
94
106
### Monitoring Third-Party Endpoints
95
107
<Aside>If you're monitoring a URL you don't own (like `google.com` or a partner API), your requests might be blocked by firewalls or rate limiters (e.g., Cloudflare). This is a security measure on their end to prevent scraping or denial-of-service attacks.</Aside>
108
+
109
+
## What you've accomplished
110
+
111
+
Congratulations! You've successfully:
112
+
- ✅ Created your first uptime monitor
113
+
- ✅ Configured basic HTTP monitoring settings
114
+
- ✅ Learned about customizing requests with methods, headers, and body
115
+
- ✅ Understood key monitoring metrics (response time, status codes, timing breakdown)
116
+
117
+
## What's next?
118
+
119
+
Now that you have a monitor running, you can:
120
+
121
+
- **[Create a Status Page](/tutorial/how-to-create-status-page)** - Share your service status publicly with users
122
+
- **[Set Up Alerting](/monitoring/customization/notification)** - Get notified when your service goes down
123
+
- **[Configure Assertions](/monitoring/customization/assertions)** - Validate response content, not just status codes
124
+
- **[Add Multiple Regions](/monitoring/customization/locations)** - Monitor from different global locations
125
+
126
+
### Learn more
127
+
128
+
- **[Understanding Uptime Monitoring](/concept/uptime-monitoring)** - Deep dive into monitoring concepts
129
+
- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - What metrics we track
130
+
- **[HTTP Monitor Reference](/reference/http-monitor)** - Complete technical specifications
96
131
97
132
98
133
+39
-4
apps/docs/src/content/docs/tutorial/how-to-create-status-page.mdx
+39
-4
apps/docs/src/content/docs/tutorial/how-to-create-status-page.mdx
···
1
1
---
2
-
title: How to create a status page?
3
-
description: "How to create a status page in OpenStatus"
2
+
title: Create a Status Page
3
+
description: "A step-by-step tutorial to create and publish your first status page"
4
4
---
5
5
6
6
import { Image } from 'astro:assets';
···
9
9
10
10
import CreateStatusPage2 from '../../../assets/tutorial/create-status-page/create-status-page-2.png';
11
11
12
+
## What you'll learn
12
13
14
+
In this tutorial, you'll create a public status page to communicate your service's health to users. A status page is a transparent way to show real-time uptime information and keep your users informed during incidents.
15
+
16
+
### Prerequisites
13
17
14
-
This tutorial will guide you through the process of creating a status page in openstatus. A status page is a web page that displays the status of your services.
18
+
- An openstatus account
19
+
- At least one monitor created (see [Create Your First Monitor](/tutorial/how-to-create-monitor))
20
+
21
+
### What you'll build
22
+
23
+
By the end of this tutorial, you'll have:
24
+
- A public status page showing your service health
25
+
- Monitors displayed on your status page
26
+
- Understanding of privacy and security options
27
+
28
+
This tutorial will guide you through the process of creating a status page in openstatus. A status page is a web page that displays the status of your services, building trust with your users through transparency.
15
29
16
30
## Get started
17
31
···
42
56
43
57
#### Custom domain
44
58
45
-
You can add a Custom Domain to your status page. Custom domains allow you to use your own domain name instead of the default domain name provided by OpenStatus.
59
+
You can add a Custom Domain to your status page. Custom domains allow you to use your own domain name instead of the default domain name provided by openstatus.
46
60
47
61
48
62
#### Password Protection
49
63
50
64
You can add password protection to your status page. Password protection allows you to restrict access to your status page to only authorized users.
65
+
66
+
## What you've accomplished
67
+
68
+
Great work! You've successfully:
69
+
- ✅ Created your first status page
70
+
- ✅ Added monitors to display service health
71
+
- ✅ Learned about custom domains and password protection
72
+
73
+
## What's next?
74
+
75
+
Now that you have a basic status page, you can:
76
+
77
+
- **[Configure Your Status Page](/tutorial/how-to-configure-status-page)** - Customize appearance and add more features
78
+
- **[Configure Notifications](/monitoring/customization/notification)** - Alert your team when issues occur
79
+
- **[Best Practices for Status Pages](/concept/best-practices-status-page)** - Learn how to communicate effectively
80
+
81
+
### Learn more
82
+
83
+
- **[Status Page Reference](/reference/status-page)** - Complete configuration options
84
+
- **[Understanding Uptime Values](/concept/uptime-calculation-and-values)** - How uptime is calculated
85
+
- **[Status Page Examples](https://www.openstatus.dev/showcase)** - See status pages from other users
-4
apps/docs/src/content/docs/tutorials.mdx
-4
apps/docs/src/content/docs/tutorials.mdx