Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
π improve docs (#594)
Thibault Le Ouay8b5832b9541b
diff --git a/apps/docs/api-reference/checker.mdx b/apps/docs/api-reference/checker.mdxindex 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.mdxsimilarity index 100%rename from apps/docs/developer-guide/get-started.mdxrename to apps/docs/contributing/get-started.mdxdiff --git a/apps/docs/developer-guide/requirements.mdx b/apps/docs/contributing/requirements.mdxsimilarity index 100%rename from apps/docs/developer-guide/requirements.mdxrename to apps/docs/contributing/requirements.mdxdiff --git a/apps/docs/developer-guide/setup-env.mdx b/apps/docs/contributing/setup-env.mdxsimilarity index 100%rename from apps/docs/developer-guide/setup-env.mdxrename to apps/docs/contributing/setup-env.mdxdiff --git a/apps/docs/developer-guide/setup.mdx b/apps/docs/contributing/setup.mdxsimilarity index 100%rename from apps/docs/developer-guide/setup.mdxrename to apps/docs/contributing/setup.mdxdiff --git a/apps/docs/features/heartbeat.mdx b/apps/docs/features/heartbeat.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxsimilarity index 61%rename from apps/docs/getting-started/monitor.mdxrename to apps/docs/features/monitor.mdxindex 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` orAdd 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 yourrequest.-### 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.mdxnew file mode 100644index 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.mdxsimilarity index 100%rename from apps/docs/integrations/discord.mdxrename to apps/docs/features/notification/discord.mdxdiff --git a/apps/docs/features/notification/email.mdx b/apps/docs/features/notification/email.mdxnew file mode 100644index 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.mdxsimilarity index 100%rename from apps/docs/integrations/phone-call.mdxrename to apps/docs/features/notification/phone-call.mdxdiff --git a/apps/docs/integrations/slack.mdx b/apps/docs/features/notification/slack.mdxsimilarity index 100%rename from apps/docs/integrations/slack.mdxrename to apps/docs/features/notification/slack.mdxdiff --git a/apps/docs/features/notification/sms.mdx b/apps/docs/features/notification/sms.mdxnew file mode 100644index 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.mdxsimilarity index 100%rename from apps/docs/integrations/telegram.mdxrename to apps/docs/features/notification/telegram.mdxdiff --git a/apps/docs/features/status-page-subscribers.mdx b/apps/docs/features/status-page-subscribers.mdxnew file mode 100644index 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.mdxsimilarity index 100%rename from apps/docs/getting-started/status-page.mdxrename to apps/docs/features/status-page.mdxdiff --git a/apps/docs/getting-started/status-report.mdx b/apps/docs/features/status-report.mdxsimilarity index 93%rename from apps/docs/getting-started/status-report.mdxrename to apps/docs/features/status-report.mdxindex 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 Reportdescription: "How to create your first report π₯"---diff --git a/apps/docs/getting-started/status-widget.mdx b/apps/docs/features/status-widget.mdxsimilarity index 100%rename from apps/docs/getting-started/status-widget.mdxrename to apps/docs/features/status-widget.mdxdiff --git a/apps/docs/getting-started/heartbeat.mdx b/apps/docs/getting-started/heartbeat.mdxdeleted file mode 100644index 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.mdxdeleted file mode 100644index 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 Managementdiff --git a/apps/docs/getting-started/notification.mdx b/apps/docs/getting-started/notification.mdxdeleted file mode 100644index 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.mdxdeleted file mode 100644index 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.mdxdeleted file mode 100644index 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.mdxindex 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 runthe 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.jsonindex 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.jsonindex 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.mdxnew file mode 100644index 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+> [[email protected]](mailto:[email protected]) or+> [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.++++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>+ );+}+```