Skip to content

Open-source status page, incident response and uptime monitoring

πŸ“ improve docs (#594)

Thibault Le Ouay8b5832b9541b
diff --git a/apps/docs/api-reference/checker.mdx b/apps/docs/api-reference/checker.mdx
index 4fb71cbf1..e69ee1b0d 100644
--- a/apps/docs/api-reference/checker.mdx
+++ b/apps/docs/api-reference/checker.mdx
@@ -87,3 +87,10 @@ type CheckerResponse = {
};
};
```
+
+You can use it to check from a region the following metrics:
+
+- DNS Look up time,
+- TLS handshake time,
+- TCP connection time,
+- Time to first byte.
diff --git a/apps/docs/developer-guide/get-started.mdx b/apps/docs/contributing/get-started.mdx
similarity index 100%
rename from apps/docs/developer-guide/get-started.mdx
rename to apps/docs/contributing/get-started.mdx
diff --git a/apps/docs/developer-guide/requirements.mdx b/apps/docs/contributing/requirements.mdx
similarity index 100%
rename from apps/docs/developer-guide/requirements.mdx
rename to apps/docs/contributing/requirements.mdx
diff --git a/apps/docs/developer-guide/setup-env.mdx b/apps/docs/contributing/setup-env.mdx
similarity index 100%
rename from apps/docs/developer-guide/setup-env.mdx
rename to apps/docs/contributing/setup-env.mdx
diff --git a/apps/docs/developer-guide/setup.mdx b/apps/docs/contributing/setup.mdx
similarity index 100%
rename from apps/docs/developer-guide/setup.mdx
rename to apps/docs/contributing/setup.mdx
diff --git a/apps/docs/features/heartbeat.mdx b/apps/docs/features/heartbeat.mdx
new file mode 100644
index 000000000..c96de2403
--- /dev/null
+++ b/apps/docs/features/heartbeat.mdx
@@ -0,0 +1,14 @@
+---
+title: Cron Monitor
+description: "How to create your first cron monitor with OpenStatus.dev"
+---
+
+## What is a Cron Monitor? πŸ€”
+
+A cron monitor allows you to monitor your cron jobs. You call your OpenStatus
+endpoint at the end of your cron job. If we haven't received your call we will
+trigger an alert and notify you.
+
+## Configure your cron monitor πŸ› 
+
+🚧 Coming soon 🚧
diff --git a/apps/docs/features/incident.mdx b/apps/docs/features/incident.mdx
new file mode 100644
index 000000000..c194dda88
--- /dev/null
+++ b/apps/docs/features/incident.mdx
@@ -0,0 +1,23 @@
+---
+title: Incident
+description: "How incident are created, how to acknowledge, and resolve themπŸ”₯"
+---
+
+## What is an incident πŸ§‘β€πŸ«
+
+We automatically create an incident when we detect a problem with your service.
+When a monitor fails in more than 50% of the locations, we create an incident.
+We do that in order to avoid false positives.
+
+## How to acknowledge an incident
+
+Go to the incident page and click on the acknowledge button.
+
+## How to resolve an incident
+
+Go to the incident page and click on the resolve button.
+
+## Auto resolve an incident πŸ”œ
+
+We automatically resolve an incident when the monitor is passing in more than
+50% of the locations.
diff --git a/apps/docs/getting-started/monitor.mdx b/apps/docs/features/monitor.mdx
similarity index 61%
rename from apps/docs/getting-started/monitor.mdx
rename to apps/docs/features/monitor.mdx
index 972e9b6c5..8d2d4bdcf 100644
--- a/apps/docs/getting-started/monitor.mdx
+++ b/apps/docs/features/monitor.mdx
@@ -15,7 +15,8 @@ Your endpoint check requires:
- a **name** to identify your monitor
- the **URL** to checked
-We will store the **response time** and the **status code** of your endpoint.
+We will store the **response time**, the **status code**, the **headers**
+returned, and the **timing metrics** of your endpoint.
<Frame caption="Monitor your endpoint">
<img
@@ -33,34 +34,39 @@ Choose between one of the request **HTTP Method**: `GET` (default), `POST` or
Add custom key-value **HTTP Headers** to your request.
-> OpenStatus automatically appends the `"OpenStatus-Ping": "true"` header to
+> OpenStatus automatically set the `"User-Agent": "OpenStatus/1.0"` header to
> your request. This header is used to identify the request as a ping request
> and can be exluded from your analytics.
If you select the `POST` method, you can add a custom **HTTP Body** to your
request.
-### Advanced Configuration ⏱️
+### Advanced Configuration βš™οΈ
-Define the **frequency** of your checks. You can choose between: `1m`, `5m`,
-`10m` (default), `30min` or `1h`.
+You can pause your monitor with the **active** switch button.
-By default, **all regions** are enabled. You can disable some regions if you
-want to. Leaving it empty will check your endpoint from a random region.
+#### Frequency ⏱
-The **description** is optional. If defined, an `Info` tooltip will be added to
-your monitor name.
+Define the **frequency** of your checks. You can choose between: `30s`, `1m`,
+`5m`, `10m` (default), `30min` or `1h`.
+
+#### Regions 🌍
-You can always pause your monitor with the **active** switch button.
+By default, **all regions** are enabled. You can disable some regions if you
+want to. Our regions are:
-### Notifications πŸ””
+- `ams` - Amsterdam, Netherlands - πŸ‡³πŸ‡±
+- `iad` - Ashburn, Virginia, USA - πŸ‡ΊπŸ‡Έ
+- `jnb` - Johannesburg, South Africa - πŸ‡ΏπŸ‡¦
+- `hkg` - Hong Kong, Honkg Kong - πŸ‡­πŸ‡°
+- `gru` - Sao Paulo, Brazil - πŸ‡§πŸ‡·
+- `syd` - Sydney, Australia - πŸ‡¦πŸ‡Ί
-Get informed whenever a check fails. You can add multiple notification channels.
+#### Description πŸ“
-We send a webhook to Slack or Discord channels. Or you can also receive an
-email.
+The **description** is optional. If defined, an `Info` tooltip will be added to
+your monitor name.
----
+#### Timeout ⏳
-> Create an API key and use it in your HTTP Headers to create your monitor
-> programmatically API.
+You can define a **timeout** for your request. The default value is `30s`.
diff --git a/apps/docs/features/notification.mdx b/apps/docs/features/notification.mdx
new file mode 100644
index 000000000..e61e0d8ec
--- /dev/null
+++ b/apps/docs/features/notification.mdx
@@ -0,0 +1,32 @@
+---
+title: Overview
+description: "How to create your first alert with OpenStatus.dev"
+---
+
+If you connect notification channels to your OpenStatus account, you can receive
+alerts when your services are down. We will contact you when an incident is
+created.
+
+<Frame caption="Create your notification channel">
+ <img
+ src="/images/notification/discord-notification.png"
+ alt="Create your notification bot"
+ />
+</Frame>
+
+## Notification channels
+
+<CardGroup cols={2}>
+ <Card title="Email βœ‰οΈ" href="/features/notification/email">
+ Receive an email
+ </Card>
+ <Card title="Slack πŸ“£" href="/features/notification/slack">
+ Get notified on Slack
+ </Card>
+ <Card title="Discord πŸ€–" href="/features/notification/discord">
+ Get notified on Discord
+ </Card>
+ <Card title="SMS πŸ“±" href="/features/notification/sms">
+ Receive a text message
+ </Card>
+</CardGroup>
diff --git a/apps/docs/integrations/discord.mdx b/apps/docs/features/notification/discord.mdx
similarity index 100%
rename from apps/docs/integrations/discord.mdx
rename to apps/docs/features/notification/discord.mdx
diff --git a/apps/docs/features/notification/email.mdx b/apps/docs/features/notification/email.mdx
new file mode 100644
index 000000000..e23dd4643
--- /dev/null
+++ b/apps/docs/features/notification/email.mdx
@@ -0,0 +1,5 @@
+---
+title: Email
+---
+
+When we create an incident we send an email to the email provided.
diff --git a/apps/docs/integrations/phone-call.mdx b/apps/docs/features/notification/phone-call.mdx
similarity index 100%
rename from apps/docs/integrations/phone-call.mdx
rename to apps/docs/features/notification/phone-call.mdx
diff --git a/apps/docs/integrations/slack.mdx b/apps/docs/features/notification/slack.mdx
similarity index 100%
rename from apps/docs/integrations/slack.mdx
rename to apps/docs/features/notification/slack.mdx
diff --git a/apps/docs/features/notification/sms.mdx b/apps/docs/features/notification/sms.mdx
new file mode 100644
index 000000000..31d935433
--- /dev/null
+++ b/apps/docs/features/notification/sms.mdx
@@ -0,0 +1,6 @@
+---
+title: SMS
+---
+
+When you subscribe to a paid plan you can receive SMS notifications when your
+monitor is down.
diff --git a/apps/docs/integrations/telegram.mdx b/apps/docs/features/notification/telegram.mdx
similarity index 100%
rename from apps/docs/integrations/telegram.mdx
rename to apps/docs/features/notification/telegram.mdx
diff --git a/apps/docs/features/status-page-subscribers.mdx b/apps/docs/features/status-page-subscribers.mdx
new file mode 100644
index 000000000..a4c9e09be
--- /dev/null
+++ b/apps/docs/features/status-page-subscribers.mdx
@@ -0,0 +1,6 @@
+---
+title: Status Page Subscribers
+---
+
+If you are on a paid plan. Your status page will have a subscribers section.
+This section will allow your users to subscribe to your status page update.
diff --git a/apps/docs/getting-started/status-page.mdx b/apps/docs/features/status-page.mdx
similarity index 100%
rename from apps/docs/getting-started/status-page.mdx
rename to apps/docs/features/status-page.mdx
diff --git a/apps/docs/getting-started/status-report.mdx b/apps/docs/features/status-report.mdx
similarity index 93%
rename from apps/docs/getting-started/status-report.mdx
rename to apps/docs/features/status-report.mdx
index 1f8134031..a015602a9 100644
--- a/apps/docs/getting-started/status-report.mdx
+++ b/apps/docs/features/status-report.mdx
@@ -1,5 +1,5 @@
---
-title: Status Report
+title: Status Page Report
description: "How to create your first report πŸ”₯"
---
diff --git a/apps/docs/getting-started/status-widget.mdx b/apps/docs/features/status-widget.mdx
similarity index 100%
rename from apps/docs/getting-started/status-widget.mdx
rename to apps/docs/features/status-widget.mdx
diff --git a/apps/docs/getting-started/heartbeat.mdx b/apps/docs/getting-started/heartbeat.mdx
deleted file mode 100644
index 1f609232e..000000000
--- a/apps/docs/getting-started/heartbeat.mdx
+++ /dev/null
@@ -1,14 +0,0 @@
----
-title: Heartbeat
-description: "How to create your first heartbeat with OpenStatus.dev"
----
-
-## What is a heartbeat? πŸ’“
-
-A heartbeat allows you to monitor your cron jobs. You call your OpenStatus
-endpoint at the end of your cron job. If we haven't received your call we will
-trigger an alert and notify you.
-
-## Configure your heartbeat πŸ› 
-
-🚧 Coming soon 🚧
diff --git a/apps/docs/getting-started/incident.mdx b/apps/docs/getting-started/incident.mdx
deleted file mode 100644
index a48e0f322..000000000
--- a/apps/docs/getting-started/incident.mdx
+++ /dev/null
@@ -1,13 +0,0 @@
----
-title: Incident
-description: "How to create your first incident πŸ”₯"
----
-
-<Warning>
- **Incidents** have been renamed to [Status
- Reports](/getting-started/status-report). That also includes the [API
- endpoint](/api-reference/status_report). It will allow us to differenciate
- between **public status reports** and **internal incident management**.
-</Warning>
-
-Coming soon: Internal Incident Management
diff --git a/apps/docs/getting-started/notification.mdx b/apps/docs/getting-started/notification.mdx
deleted file mode 100644
index 1c3a4b1c4..000000000
--- a/apps/docs/getting-started/notification.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
----
-title: Notification
-description: "How to create your first alert with OpenStatus.dev"
----
-
-You get notified when your monitor has failed. Configure multiple alerts for
-each monitor.
-
-We support the following notification channels: **email**, **slack** and
-**discord**.
-
-<Frame caption="Create your notification channel">
- <img
- src="/images/notification/discord-notification.png"
- alt="Create your notification bot"
- />
-</Frame>
-
-### Email βœ‰οΈ
-
-Enter your email address in the alert configuration.
-
-### Slack πŸ“£
-
-Create an [incoming webhook](https://api.slack.com/messaging/webhooks) in your
-Slack workspace. Copy the webhook URL and paste it in the alert configuration.
-
-### Discord πŸ€–
-
-Create a
-[webhook](https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks)
-in your Discord server. Copy the webhook URL and paste it in the alert
-configuration.
diff --git a/apps/docs/incident-automation/get-started.mdx b/apps/docs/incident-automation/get-started.mdx
deleted file mode 100644
index 2056b3a00..000000000
--- a/apps/docs/incident-automation/get-started.mdx
+++ /dev/null
@@ -1,20 +0,0 @@
----
-title: Incident Automation
-description: "How to use incident automation"
----
-
-# What is incident automation? πŸ€”
-
-When you have an incident, you might need to perform a series of actions to
-handle it. For example, you might need to:
-
-- create a slack channel
-- create a google meet meeting
-- create a Linear ticket
-- Perform a checklist of actions
-
-Incident automation allows you to automate these actions.
-
-## How to define an incident automation? πŸ€–
-
-Incident automation is defined in a YAML file.
diff --git a/apps/docs/integrations/sms.mdx b/apps/docs/integrations/sms.mdx
deleted file mode 100644
index b6e0427d3..000000000
--- a/apps/docs/integrations/sms.mdx
+++ /dev/null
@@ -1,7 +0,0 @@
----
-title: SMS
----
-
-Receive a SMS when your monitor is down.
-
-🚧 Coming soon 🚧
diff --git a/apps/docs/introduction.mdx b/apps/docs/introduction.mdx
index b17e79b90..8ab3fcf77 100644
--- a/apps/docs/introduction.mdx
+++ b/apps/docs/introduction.mdx
@@ -21,20 +21,3 @@ There are three ways to get started with OpenStatus.
the app
- **Self-hosting**: if you want greater control over your data and want to run
the app on your own server
-
-## Start with OpenStatus
-
-<CardGroup cols={2}>
- <Card title="Monitor" href="/getting-started/monitor">
- Learn how to create your first monitor
- </Card>
- <Card title="Status Page" href="/getting-started/status-page">
- Learn how to set up your status page
- </Card>
- <Card title="Notification" href="/getting-started/notification">
- Learn how to set up alerting for your monitors
- </Card>
- <Card title="Incident" href="/getting-started/incident">
- Learn how to create your first incident
- </Card>
-</CardGroup>
diff --git a/apps/docs/mint.json b/apps/docs/mint.json
index 9b7408648..ac8fddc4d 100644
--- a/apps/docs/mint.json
+++ b/apps/docs/mint.json
@@ -49,6 +49,10 @@
{
"name": "API Reference",
"url": "api-reference"
+ },
+ {
+ "name": "Contributor Guides",
+ "url": "contributing"
}
],
"anchors": [
@@ -66,49 +70,51 @@
"navigation": [
{
"group": "Introduction",
+ "pages": ["introduction"]
+ },
+ {
+ "group": "Features",
+
"pages": [
- "introduction",
+ "features/incident",
+ "features/heartbeat",
+ "features/monitor",
+
{
- "group": "Getting Started",
+ "group": "Notifications",
"pages": [
- "getting-started/monitor",
- "getting-started/status-page",
- "getting-started/incident",
- "getting-started/status-report",
- "getting-started/notification",
- "getting-started/heartbeat"
+ "features/notification",
+ {
+ "group": "Notification Channels",
+ "pages": [
+ "features/notification/discord",
+ "features/notification/phone-call",
+ "features/notification/slack",
+ "features/notification/sms",
+ "features/notification/telegram"
+ ]
+ }
]
},
- "getting-started/status-widget"
+ "features/status-page",
+ "features/status-report",
+ "features/status-page-subscribers"
]
},
{
- "group": "Incident Management",
- "pages": ["incident-automation/get-started"]
- },
- {
- "group": "Developer Guides",
- "pages": [
- "developer-guide/requirements",
- "developer-guide/get-started",
- "developer-guide/setup-env",
- "developer-guide/setup"
- ]
+ "group": "Developer Tools",
+ "pages": ["packages/react", "packages/status-widget"]
},
+
{
- "group": "Integrations",
+ "group": "Contributor Guides",
"pages": [
- "integrations/discord",
- "integrations/phone-call",
- "integrations/slack",
- "integrations/sms",
- "integrations/telegram"
+ "contributing/requirements",
+ "contributing/get-started",
+ "contributing/setup-env",
+ "contributing/setup"
]
},
- {
- "group": "Libraries",
- "pages": ["packages/react"]
- },
{
"group": "API Documentation",
"icon": "code",
diff --git a/apps/docs/package.json b/apps/docs/package.json
index 287687c80..43290259c 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -3,8 +3,8 @@
"version": "0.0.0",
"private": true,
"scripts": {
- "dev": "npx mintlify@latest dev",
- "verify": "npx mintlify@latest broken-links"
+ "dev": "pnpm dlx mintlify@latest dev",
+ "verify": "pnpm dlx mintlify@latest broken-links"
},
"keywords": [],
"author": "OpenStatus"
diff --git a/apps/docs/packages/status-widget.mdx b/apps/docs/packages/status-widget.mdx
new file mode 100644
index 000000000..759cdfc0b
--- /dev/null
+++ b/apps/docs/packages/status-widget.mdx
@@ -0,0 +1,162 @@
+---
+title: Public Status Widget
+description: "How to add a public status widget to your website."
+---
+
+We have added a public endpoint where you can access the status of your status
+page. To access it, you only need the unique `:slug` you have chosen for your
+page.
+
+```bash
+curl https://api.openstatus.dev/public/status/:slug
+```
+
+<Callout type="info">
+ We have released an `@openstatus/react` npm package that allows you to easily
+ integrate the pre-typed status into your React projects or use the default
+ widget. Read more [here](/packages/react).
+</Callout>
+
+The response is a JSON object with the following structure:
+
+```json
+{ "status": "operational" }
+```
+
+in which the status can be one of the following values:
+
+```ts
+enum Status {
+ Operational = "operational",
+ DegradedPerformance = "degraded_performance",
+ PartialOutage = "partial_outage",
+ MajorOutage = "major_outage",
+ UnderMaintenance = "under_maintenance", // currently not in use
+ Unknown = "unknown",
+ Incident = "incident",
+}
+```
+
+### How does it work?
+
+The status is calculated by the ratio `uptime / (uptime + downtime)` of the last
+5 cron jobs of each monitor which we accumulate together. It is a simple
+calculation that gives us a good overview of the status of your services.
+
+```ts
+function getStatus(ratio: number) {
+ if (isNaN(ratio)) return Status.Unknown;
+ if (ratio >= 0.98) return Status.Operational;
+ if (ratio >= 0.6) return Status.DegradedPerformance;
+ if (ratio >= 0.3) return Status.PartialOutage;
+ if (ratio >= 0) return Status.MajorOutage;
+ return Status.Unknown;
+}
+```
+
+We are caching the result for `30 seconds` to reduce the load on our database.
+
+The `Status.Incident` will always be returned when then status of any incident
+on your page is **not** _"monitoring"_ or _"resolved"_. You can attach an
+incident to a monitor (implicit) or a page (explicit).
+
+> If you have a doubt about the above calculation, feel free to contact us via
+> [discord](https://openstatus.dev/discord).
+
+### React Widget
+
+We currently do not provide any SDK or package to integrate the status into your
+stack. But will in the future.
+
+If you are using Nextjs and RSC with the `/app` directory, feel free to use that
+Component. Small reminder that we are using shadcn ui and tailwindcss. You might
+want to update the `bg-muted` and `text-foreground` classes to your needs.
+
+![Status Widget](/images/status-widget/widget-example.png)
+
+We are using `zod` to validate the response. You can use any other library if
+you want or just remove it. But better be safe than sorry.
+
+```tsx
+import * as z from "zod";
+
+const statusEnum = z.enum([
+ "operational",
+ "degraded_performance",
+ "partial_outage",
+ "major_outage",
+ "under_maintenance",
+ "unknown",
+ "incident",
+]);
+
+const statusSchema = z.object({ status: statusEnum });
+
+const dictionary = {
+ operational: {
+ label: "Operational",
+ color: "bg-green-500",
+ },
+ degraded_performance: {
+ label: "Degraded Performance",
+ color: "bg-yellow-500",
+ },
+ partial_outage: {
+ label: "Partial Outage",
+ color: "bg-yellow-500",
+ },
+ major_outage: {
+ label: "Major Outage",
+ color: "bg-red-500",
+ },
+ unknown: {
+ label: "Unknown",
+ color: "bg-gray-500",
+ },
+ incident: {
+ label: "Incident",
+ color: "bg-yellow-500",
+ },
+ under_maintenance: {
+ label: "Under Maintenance",
+ color: "bg-gray-500",
+ },
+} as const;
+
+export async function StatusWidget({ slug }: { slug: string }) {
+ const res = await fetch(`https://api.openstatus.dev/public/status/${slug}`, {
+ next: { revalidate: 60 }, // cache request for 60 seconds
+ });
+ const data = await res.json();
+ const parsed = statusSchema.safeParse(data);
+
+ if (!parsed.success) {
+ return null;
+ }
+
+ const key = parsed.data.status;
+ const { label, color } = dictionary[key];
+
+ return (
+ <a
+ 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"
+ href={`https://${slug}.openstatus.dev`}
+ target="_blank"
+ rel="noreferrer"
+ >
+ {label}
+ <span className="relative flex h-2 w-2">
+ {parsed.data.status === "operational" ? (
+ <span
+ className={`absolute inline-flex h-full w-full animate-ping rounded-full ${color} opacity-75 duration-1000`}
+ />
+ ) : null}
+ <span
+ className={`relative inline-flex h-2 w-2 rounded-full ${color}`}
+ />
+ </span>
+ </a>
+ );
+}
+```