openstatus.dev
Openstatus
www.openstatus.dev
📝 improve docs (#594)
authored by
Thibault Le Ouay
and committed by
GitHub
8b5832b9
c732e129
+317
-154
+7
apps/docs/api-reference/checker.mdx
+7
apps/docs/api-reference/checker.mdx
apps/docs/developer-guide/get-started.mdx
apps/docs/contributing/get-started.mdx
apps/docs/developer-guide/get-started.mdx
apps/docs/contributing/get-started.mdx
apps/docs/developer-guide/requirements.mdx
apps/docs/contributing/requirements.mdx
apps/docs/developer-guide/requirements.mdx
apps/docs/contributing/requirements.mdx
apps/docs/developer-guide/setup-env.mdx
apps/docs/contributing/setup-env.mdx
apps/docs/developer-guide/setup-env.mdx
apps/docs/contributing/setup-env.mdx
apps/docs/developer-guide/setup.mdx
apps/docs/contributing/setup.mdx
apps/docs/developer-guide/setup.mdx
apps/docs/contributing/setup.mdx
+14
apps/docs/features/heartbeat.mdx
+14
apps/docs/features/heartbeat.mdx
···
1
+
---
2
+
title: Cron Monitor
3
+
description: "How to create your first cron monitor with OpenStatus.dev"
4
+
---
5
+
6
+
## What is a Cron Monitor? 🤔
7
+
8
+
A cron monitor allows you to monitor your cron jobs. You call your OpenStatus
9
+
endpoint at the end of your cron job. If we haven't received your call we will
10
+
trigger an alert and notify you.
11
+
12
+
## Configure your cron monitor 🛠
13
+
14
+
🚧 Coming soon 🚧
+23
apps/docs/features/incident.mdx
+23
apps/docs/features/incident.mdx
···
1
+
---
2
+
title: Incident
3
+
description: "How incident are created, how to acknowledge, and resolve them🔥"
4
+
---
5
+
6
+
## What is an incident 🧑🏫
7
+
8
+
We automatically create an incident when we detect a problem with your service.
9
+
When a monitor fails in more than 50% of the locations, we create an incident.
10
+
We do that in order to avoid false positives.
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.
+32
apps/docs/features/notification.mdx
+32
apps/docs/features/notification.mdx
···
1
+
---
2
+
title: Overview
3
+
description: "How to create your first alert with OpenStatus.dev"
4
+
---
5
+
6
+
If you connect notification channels to your OpenStatus account, you can receive
7
+
alerts when your services are down. We will contact you when an incident is
8
+
created.
9
+
10
+
<Frame caption="Create your notification channel">
11
+
<img
12
+
src="/images/notification/discord-notification.png"
13
+
alt="Create your notification bot"
14
+
/>
15
+
</Frame>
16
+
17
+
## Notification channels
18
+
19
+
<CardGroup cols={2}>
20
+
<Card title="Email ✉️" href="/features/notification/email">
21
+
Receive an email
22
+
</Card>
23
+
<Card title="Slack 📣" href="/features/notification/slack">
24
+
Get notified on Slack
25
+
</Card>
26
+
<Card title="Discord 🤖" href="/features/notification/discord">
27
+
Get notified on Discord
28
+
</Card>
29
+
<Card title="SMS 📱" href="/features/notification/sms">
30
+
Receive a text message
31
+
</Card>
32
+
</CardGroup>
+5
apps/docs/features/notification/email.mdx
+5
apps/docs/features/notification/email.mdx
+6
apps/docs/features/notification/sms.mdx
+6
apps/docs/features/notification/sms.mdx
+6
apps/docs/features/status-page-subscribers.mdx
+6
apps/docs/features/status-page-subscribers.mdx
-14
apps/docs/getting-started/heartbeat.mdx
-14
apps/docs/getting-started/heartbeat.mdx
···
1
-
---
2
-
title: Heartbeat
3
-
description: "How to create your first heartbeat with OpenStatus.dev"
4
-
---
5
-
6
-
## What is a heartbeat? 💓
7
-
8
-
A heartbeat allows you to monitor your cron jobs. You call your OpenStatus
9
-
endpoint at the end of your cron job. If we haven't received your call we will
10
-
trigger an alert and notify you.
11
-
12
-
## Configure your heartbeat 🛠
13
-
14
-
🚧 Coming soon 🚧
-13
apps/docs/getting-started/incident.mdx
-13
apps/docs/getting-started/incident.mdx
···
1
-
---
2
-
title: Incident
3
-
description: "How to create your first incident 🔥"
4
-
---
5
-
6
-
<Warning>
7
-
**Incidents** have been renamed to [Status
8
-
Reports](/getting-started/status-report). That also includes the [API
9
-
endpoint](/api-reference/status_report). It will allow us to differenciate
10
-
between **public status reports** and **internal incident management**.
11
-
</Warning>
12
-
13
-
Coming soon: Internal Incident Management
+23
-17
apps/docs/getting-started/monitor.mdx
apps/docs/features/monitor.mdx
+23
-17
apps/docs/getting-started/monitor.mdx
apps/docs/features/monitor.mdx
···
15
15
- a **name** to identify your monitor
16
16
- the **URL** to checked
17
17
18
-
We will store the **response time** and the **status code** of your endpoint.
18
+
We will store the **response time**, the **status code**, the **headers**
19
+
returned, and the **timing metrics** of your endpoint.
19
20
20
21
<Frame caption="Monitor your endpoint">
21
22
<img
···
33
34
34
35
Add custom key-value **HTTP Headers** to your request.
35
36
36
-
> OpenStatus automatically appends the `"OpenStatus-Ping": "true"` header to
37
+
> OpenStatus automatically set the `"User-Agent": "OpenStatus/1.0"` header to
37
38
> your request. This header is used to identify the request as a ping request
38
39
> and can be exluded from your analytics.
39
40
40
41
If you select the `POST` method, you can add a custom **HTTP Body** to your
41
42
request.
42
43
43
-
### Advanced Configuration ⏱️
44
+
### Advanced Configuration ⚙️
44
45
45
-
Define the **frequency** of your checks. You can choose between: `1m`, `5m`,
46
-
`10m` (default), `30min` or `1h`.
46
+
You can pause your monitor with the **active** switch button.
47
47
48
-
By default, **all regions** are enabled. You can disable some regions if you
49
-
want to. Leaving it empty will check your endpoint from a random region.
48
+
#### Frequency ⏱
50
49
51
-
The **description** is optional. If defined, an `Info` tooltip will be added to
52
-
your monitor name.
50
+
Define the **frequency** of your checks. You can choose between: `30s`, `1m`,
51
+
`5m`, `10m` (default), `30min` or `1h`.
53
52
54
-
You can always pause your monitor with the **active** switch button.
53
+
#### Regions 🌍
55
54
56
-
### Notifications 🔔
55
+
By default, **all regions** are enabled. You can disable some regions if you
56
+
want to. Our regions are:
57
57
58
-
Get informed whenever a check fails. You can add multiple notification channels.
58
+
- `ams` - Amsterdam, Netherlands - 🇳🇱
59
+
- `iad` - Ashburn, Virginia, USA - 🇺🇸
60
+
- `jnb` - Johannesburg, South Africa - 🇿🇦
61
+
- `hkg` - Hong Kong, Honkg Kong - 🇭🇰
62
+
- `gru` - Sao Paulo, Brazil - 🇧🇷
63
+
- `syd` - Sydney, Australia - 🇦🇺
59
64
60
-
We send a webhook to Slack or Discord channels. Or you can also receive an
61
-
email.
65
+
#### Description 📝
62
66
63
-
---
67
+
The **description** is optional. If defined, an `Info` tooltip will be added to
68
+
your monitor name.
64
69
65
-
> Create an API key and use it in your HTTP Headers to create your monitor
66
-
> programmatically API.
70
+
#### Timeout ⏳
71
+
72
+
You can define a **timeout** for your request. The default value is `30s`.
-33
apps/docs/getting-started/notification.mdx
-33
apps/docs/getting-started/notification.mdx
···
1
-
---
2
-
title: Notification
3
-
description: "How to create your first alert with OpenStatus.dev"
4
-
---
5
-
6
-
You get notified when your monitor has failed. Configure multiple alerts for
7
-
each monitor.
8
-
9
-
We support the following notification channels: **email**, **slack** and
10
-
**discord**.
11
-
12
-
<Frame caption="Create your notification channel">
13
-
<img
14
-
src="/images/notification/discord-notification.png"
15
-
alt="Create your notification bot"
16
-
/>
17
-
</Frame>
18
-
19
-
### Email ✉️
20
-
21
-
Enter your email address in the alert configuration.
22
-
23
-
### Slack 📣
24
-
25
-
Create an [incoming webhook](https://api.slack.com/messaging/webhooks) in your
26
-
Slack workspace. Copy the webhook URL and paste it in the alert configuration.
27
-
28
-
### Discord 🤖
29
-
30
-
Create a
31
-
[webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks)
32
-
in your Discord server. Copy the webhook URL and paste it in the alert
33
-
configuration.
apps/docs/getting-started/status-page.mdx
apps/docs/features/status-page.mdx
apps/docs/getting-started/status-page.mdx
apps/docs/features/status-page.mdx
+1
-1
apps/docs/getting-started/status-report.mdx
apps/docs/features/status-report.mdx
+1
-1
apps/docs/getting-started/status-report.mdx
apps/docs/features/status-report.mdx
apps/docs/getting-started/status-widget.mdx
apps/docs/features/status-widget.mdx
apps/docs/getting-started/status-widget.mdx
apps/docs/features/status-widget.mdx
-20
apps/docs/incident-automation/get-started.mdx
-20
apps/docs/incident-automation/get-started.mdx
···
1
-
---
2
-
title: Incident Automation
3
-
description: "How to use incident automation"
4
-
---
5
-
6
-
# What is incident automation? 🤔
7
-
8
-
When you have an incident, you might need to perform a series of actions to
9
-
handle it. For example, you might need to:
10
-
11
-
- create a slack channel
12
-
- create a google meet meeting
13
-
- create a Linear ticket
14
-
- Perform a checklist of actions
15
-
16
-
Incident automation allows you to automate these actions.
17
-
18
-
## How to define an incident automation? 🤖
19
-
20
-
Incident automation is defined in a YAML file.
apps/docs/integrations/discord.mdx
apps/docs/features/notification/discord.mdx
apps/docs/integrations/discord.mdx
apps/docs/features/notification/discord.mdx
apps/docs/integrations/phone-call.mdx
apps/docs/features/notification/phone-call.mdx
apps/docs/integrations/phone-call.mdx
apps/docs/features/notification/phone-call.mdx
apps/docs/integrations/slack.mdx
apps/docs/features/notification/slack.mdx
apps/docs/integrations/slack.mdx
apps/docs/features/notification/slack.mdx
-7
apps/docs/integrations/sms.mdx
-7
apps/docs/integrations/sms.mdx
apps/docs/integrations/telegram.mdx
apps/docs/features/notification/telegram.mdx
apps/docs/integrations/telegram.mdx
apps/docs/features/notification/telegram.mdx
-17
apps/docs/introduction.mdx
-17
apps/docs/introduction.mdx
···
21
21
the app
22
22
- **Self-hosting**: if you want greater control over your data and want to run
23
23
the app on your own server
24
-
25
-
## Start with OpenStatus
26
-
27
-
<CardGroup cols={2}>
28
-
<Card title="Monitor" href="/getting-started/monitor">
29
-
Learn how to create your first monitor
30
-
</Card>
31
-
<Card title="Status Page" href="/getting-started/status-page">
32
-
Learn how to set up your status page
33
-
</Card>
34
-
<Card title="Notification" href="/getting-started/notification">
35
-
Learn how to set up alerting for your monitors
36
-
</Card>
37
-
<Card title="Incident" href="/getting-started/incident">
38
-
Learn how to create your first incident
39
-
</Card>
40
-
</CardGroup>
+36
-30
apps/docs/mint.json
+36
-30
apps/docs/mint.json
···
49
49
{
50
50
"name": "API Reference",
51
51
"url": "api-reference"
52
+
},
53
+
{
54
+
"name": "Contributor Guides",
55
+
"url": "contributing"
52
56
}
53
57
],
54
58
"anchors": [
···
66
70
"navigation": [
67
71
{
68
72
"group": "Introduction",
73
+
"pages": ["introduction"]
74
+
},
75
+
{
76
+
"group": "Features",
77
+
69
78
"pages": [
70
-
"introduction",
79
+
"features/incident",
80
+
"features/heartbeat",
81
+
"features/monitor",
82
+
71
83
{
72
-
"group": "Getting Started",
84
+
"group": "Notifications",
73
85
"pages": [
74
-
"getting-started/monitor",
75
-
"getting-started/status-page",
76
-
"getting-started/incident",
77
-
"getting-started/status-report",
78
-
"getting-started/notification",
79
-
"getting-started/heartbeat"
86
+
"features/notification",
87
+
{
88
+
"group": "Notification Channels",
89
+
"pages": [
90
+
"features/notification/discord",
91
+
"features/notification/phone-call",
92
+
"features/notification/slack",
93
+
"features/notification/sms",
94
+
"features/notification/telegram"
95
+
]
96
+
}
80
97
]
81
98
},
82
-
"getting-started/status-widget"
99
+
"features/status-page",
100
+
"features/status-report",
101
+
"features/status-page-subscribers"
83
102
]
84
103
},
85
104
{
86
-
"group": "Incident Management",
87
-
"pages": ["incident-automation/get-started"]
105
+
"group": "Developer Tools",
106
+
"pages": ["packages/react", "packages/status-widget"]
88
107
},
108
+
89
109
{
90
-
"group": "Developer Guides",
110
+
"group": "Contributor Guides",
91
111
"pages": [
92
-
"developer-guide/requirements",
93
-
"developer-guide/get-started",
94
-
"developer-guide/setup-env",
95
-
"developer-guide/setup"
112
+
"contributing/requirements",
113
+
"contributing/get-started",
114
+
"contributing/setup-env",
115
+
"contributing/setup"
96
116
]
97
-
},
98
-
{
99
-
"group": "Integrations",
100
-
"pages": [
101
-
"integrations/discord",
102
-
"integrations/phone-call",
103
-
"integrations/slack",
104
-
"integrations/sms",
105
-
"integrations/telegram"
106
-
]
107
-
},
108
-
{
109
-
"group": "Libraries",
110
-
"pages": ["packages/react"]
111
117
},
112
118
{
113
119
"group": "API Documentation",
+2
-2
apps/docs/package.json
+2
-2
apps/docs/package.json
···
3
3
"version": "0.0.0",
4
4
"private": true,
5
5
"scripts": {
6
-
"dev": "npx mintlify@latest dev",
7
-
"verify": "npx mintlify@latest broken-links"
6
+
"dev": "pnpm dlx mintlify@latest dev",
7
+
"verify": "pnpm dlx mintlify@latest broken-links"
8
8
},
9
9
"keywords": [],
10
10
"author": "OpenStatus"
+162
apps/docs/packages/status-widget.mdx
+162
apps/docs/packages/status-widget.mdx
···
1
+
---
2
+
title: Public Status Widget
3
+
description: "How to add a public status widget to your website."
4
+
---
5
+
6
+
We have added a public endpoint where you can access the status of your status
7
+
page. To access it, you only need the unique `:slug` you have chosen for your
8
+
page.
9
+
10
+
```bash
11
+
curl https://api.openstatus.dev/public/status/:slug
12
+
```
13
+
14
+
<Callout type="info">
15
+
We have released an `@openstatus/react` npm package that allows you to easily
16
+
integrate the pre-typed status into your React projects or use the default
17
+
widget. Read more [here](/packages/react).
18
+
</Callout>
19
+
20
+
The response is a JSON object with the following structure:
21
+
22
+
```json
23
+
{ "status": "operational" }
24
+
```
25
+
26
+
in which the status can be one of the following values:
27
+
28
+
```ts
29
+
enum Status {
30
+
Operational = "operational",
31
+
DegradedPerformance = "degraded_performance",
32
+
PartialOutage = "partial_outage",
33
+
MajorOutage = "major_outage",
34
+
UnderMaintenance = "under_maintenance", // currently not in use
35
+
Unknown = "unknown",
36
+
Incident = "incident",
37
+
}
38
+
```
39
+
40
+
### How does it work?
41
+
42
+
The status is calculated by the ratio `uptime / (uptime + downtime)` of the last
43
+
5 cron jobs of each monitor which we accumulate together. It is a simple
44
+
calculation that gives us a good overview of the status of your services.
45
+
46
+
```ts
47
+
function getStatus(ratio: number) {
48
+
if (isNaN(ratio)) return Status.Unknown;
49
+
if (ratio >= 0.98) return Status.Operational;
50
+
if (ratio >= 0.6) return Status.DegradedPerformance;
51
+
if (ratio >= 0.3) return Status.PartialOutage;
52
+
if (ratio >= 0) return Status.MajorOutage;
53
+
return Status.Unknown;
54
+
}
55
+
```
56
+
57
+
We are caching the result for `30 seconds` to reduce the load on our database.
58
+
59
+
The `Status.Incident` will always be returned when then status of any incident
60
+
on your page is **not** _"monitoring"_ or _"resolved"_. You can attach an
61
+
incident to a monitor (implicit) or a page (explicit).
62
+
63
+
> If you have a doubt about the above calculation, feel free to contact us via
64
+
> [ping@openstatus.dev](mailto:ping@openstatus.dev) or
65
+
> [discord](https://openstatus.dev/discord).
66
+
67
+
### React Widget
68
+
69
+
We currently do not provide any SDK or package to integrate the status into your
70
+
stack. But will in the future.
71
+
72
+
If you are using Nextjs and RSC with the `/app` directory, feel free to use that
73
+
Component. Small reminder that we are using shadcn ui and tailwindcss. You might
74
+
want to update the `bg-muted` and `text-foreground` classes to your needs.
75
+
76
+
77
+
78
+
We are using `zod` to validate the response. You can use any other library if
79
+
you want or just remove it. But better be safe than sorry.
80
+
81
+
```tsx
82
+
import * as z from "zod";
83
+
84
+
const statusEnum = z.enum([
85
+
"operational",
86
+
"degraded_performance",
87
+
"partial_outage",
88
+
"major_outage",
89
+
"under_maintenance",
90
+
"unknown",
91
+
"incident",
92
+
]);
93
+
94
+
const statusSchema = z.object({ status: statusEnum });
95
+
96
+
const dictionary = {
97
+
operational: {
98
+
label: "Operational",
99
+
color: "bg-green-500",
100
+
},
101
+
degraded_performance: {
102
+
label: "Degraded Performance",
103
+
color: "bg-yellow-500",
104
+
},
105
+
partial_outage: {
106
+
label: "Partial Outage",
107
+
color: "bg-yellow-500",
108
+
},
109
+
major_outage: {
110
+
label: "Major Outage",
111
+
color: "bg-red-500",
112
+
},
113
+
unknown: {
114
+
label: "Unknown",
115
+
color: "bg-gray-500",
116
+
},
117
+
incident: {
118
+
label: "Incident",
119
+
color: "bg-yellow-500",
120
+
},
121
+
under_maintenance: {
122
+
label: "Under Maintenance",
123
+
color: "bg-gray-500",
124
+
},
125
+
} as const;
126
+
127
+
export async function StatusWidget({ slug }: { slug: string }) {
128
+
const res = await fetch(`https://api.openstatus.dev/public/status/${slug}`, {
129
+
next: { revalidate: 60 }, // cache request for 60 seconds
130
+
});
131
+
const data = await res.json();
132
+
const parsed = statusSchema.safeParse(data);
133
+
134
+
if (!parsed.success) {
135
+
return null;
136
+
}
137
+
138
+
const key = parsed.data.status;
139
+
const { label, color } = dictionary[key];
140
+
141
+
return (
142
+
<a
143
+
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"
144
+
href={`https://${slug}.openstatus.dev`}
145
+
target="_blank"
146
+
rel="noreferrer"
147
+
>
148
+
{label}
149
+
<span className="relative flex h-2 w-2">
150
+
{parsed.data.status === "operational" ? (
151
+
<span
152
+
className={`absolute inline-flex h-full w-full animate-ping rounded-full ${color} opacity-75 duration-1000`}
153
+
/>
154
+
) : null}
155
+
<span
156
+
className={`relative inline-flex h-2 w-2 rounded-full ${color}`}
157
+
/>
158
+
</span>
159
+
</a>
160
+
);
161
+
}
162
+
```