Skip to content

Open-source status page, incident response and uptime monitoring

๐Ÿ“„ Docs using diataxis (#1350)

Thibault Le Ouay960ece0b58d8
diff --git a/apps/checker/http.go b/apps/checker/http.go
index 75b86682a..49ececce1 100644
--- a/apps/checker/http.go
+++ b/apps/checker/http.go
@@ -112,8 +112,8 @@ func Http(ctx context.Context, client *http.Client, inputData request.HttpChecke
start := time.Now()
response, err := client.Do(req)
- timing.TransferDone = time.Now().UTC().UnixMilli()
latency := time.Since(start).Milliseconds()
+
if err != nil {
var urlErr *url.Error
@@ -134,6 +134,9 @@ func Http(ctx context.Context, client *http.Client, inputData request.HttpChecke
defer response.Body.Close()
body, err := io.ReadAll(response.Body)
+
+ timing.TransferDone = time.Now().UTC().UnixMilli()
+
if err != nil {
return Response{
Latency: latency,
diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs
index 476382e1c..157e182fb 100644
--- a/apps/docs/astro.config.mjs
+++ b/apps/docs/astro.config.mjs
@@ -4,7 +4,6 @@ import tailwindcss from "@tailwindcss/vite";
import { defineConfig, envField } from "astro/config";
import starlightImageZoom from "starlight-image-zoom";
import starlightLlmsTxt from "starlight-llms-txt";
-import starlightSidebarTopics from "starlight-sidebar-topics";
import Icons from "unplugin-icons/vite";
@@ -58,217 +57,122 @@ export default defineConfig({
"./src/global.css",
"./src/custom.css",
],
- plugins: [
- starlightSidebarTopics([
- {
- label: "Documentation",
- link: "/",
- id: "docs",
- icon: "open-book",
- items: [
- {
- label: "Getting Started",
- items: [
- {
- label: "Introduction",
- slug: "getting-started/introduction",
- },
- ],
- },
- {
- label: "Monitoring",
- items: [
- { label: "Overview", slug: "monitoring/overview" },
- {
- label: "Create a monitor",
- slug: "monitoring/create-monitor",
- },
- {
- label: "Monitoring as Code",
- slug: "monitoring/monitoring-as-code",
- },
- {
- label: "View your results data",
- slug: "monitoring/monitor-data-collected",
- },
- {
- label: "Group your checks",
- slug: "monitoring/group-monitor-tag",
- },
- {
- label: "Clone a check",
- slug: "monitoring/clone-monitor",
- },
- {
- label: "OpenTelemetry",
- slug: "monitoring/opentelemetry",
- },
- {
- label: "Check Types",
- collapsed: true,
- items: [
- {
- label: "HTTP",
- slug: "monitoring/type/http",
- },
- {
- label: "TCP",
- slug: "monitoring/type/tcp",
- },
- ],
- },
- {
- label: "Customizations",
- collapsed: true,
- items: [
- {
- label: "Assertions",
- slug: "monitoring/customization/assertions",
- },
- {
- label: "Frequency",
- slug: "monitoring/customization/frequency",
- },
- {
- label: "Notifications",
- slug: "monitoring/customization/notification",
- },
- {
- label: "Locations",
- slug: "monitoring/customization/locations",
- },
- {
- label: "Timing",
- slug: "monitoring/customization/timing",
- },
- {
- label: "Follow Redirects",
- slug: "monitoring/customization/follow-redirects",
- },
- ],
- },
- ],
- collapsed: false,
- },
- {
- label: "Status Page",
- collapsed: true,
-
- items: [
- { label: "Overview", slug: "status-page/overview" },
- {
- label: "Create your status page",
- slug: "status-page/create-status-page",
- },
-
- {
- label: "Work with Status Page",
- autogenerate: { directory: "status-page/work" },
- collapsed: false,
- },
- {
- label: "Advanced",
- autogenerate: { directory: "status-page/advanced" },
- collapsed: true,
- },
- ],
- },
- {
- label: "Incidents",
- collapsed: true,
- items: [
- { label: "Overview", slug: "incident/overview" },
- {
- label: "Work with incident",
- slug: "incident/work-with-incident",
- },
+ sidebar: [
+ {
+ label: "Concepts",
+ items: [
+ {
+ label: "About Uptime monitoring",
+ slug: "concept/uptime-monitoring",
+ },
+ {
+ label: "Best Practices for Status Pages",
+ slug: "concept/best-practices-status-page",
+ },
+ {
+ label: "Uptime Monitoring as Code",
+ slug: "concept/uptime-monitoring-as-code",
+ },
+ {
+ label: "Latency vs Response Time",
+ slug: "concept/latency-vs-response-time",
+ },
+ ],
+ },
+ {
+ label: "Tutorials",
+ items: [
+ {
+ label: "How to create a monitor",
+ slug: "tutorial/how-to-create-monitor",
+ },
+ {
+ label: "How to create a status page",
+ slug: "tutorial/how-to-create-status-page",
+ },
+ {
+ label: "Get Started with OpenStatus CLI",
+ slug: "tutorial/get-started-with-openstatus-cli",
+ },
+ ],
+ },
- {
- label: "Incident Detail",
- slug: "incident/incident-detail",
- },
- ],
- },
- {
- label: "Alerting",
- collapsed: true,
- items: [
- { label: "Overview", slug: "alerting/overview" },
- {
- label: "Notification Channels",
- autogenerate: {
- directory: "alerting/providers",
- collapsed: true,
- },
- },
- ],
- },
- {
- label: "Developer Tools",
- collapsed: true,
- autogenerate: { directory: "tools" },
- },
- {
- label: "Support",
- collapsed: true,
- items: [
- {
- label: "Help",
- slug: "help/support",
- collapsed: true,
- },
- ],
- },
- ],
- },
- {
- label: "CLI",
- icon: "seti:powershell",
- link: "/cli/getting-started",
- items: [
- {
- label: "CLI",
- items: [
- {
- label: "Getting Started",
- slug: "cli/getting-started",
- },
- {
- label: "Commands",
- autogenerate: { directory: "cli/commands" },
- },
- ],
- },
- ],
- },
- {
- label: "API Reference",
- icon: "puzzle",
- link: "https://api.openstatus.dev/v1",
- },
- {
- label: "Guides",
- icon: "rocket",
- link: "/guides/introduction",
- items: [
- {
- label: "Guides",
- autogenerate: { directory: "guides" },
- },
- ],
- },
- {
- label: "Contributing",
- icon: "heart",
- link: "/contributing/getting-started",
- items: [
- {
- label: "Contributing",
- autogenerate: { directory: "contributing" },
+ {
+ label: "Guides",
+ items: [
+ {
+ label: "Monitor your MCP Server",
+ slug: "guides/how-to-monitor-mcp-server",
+ },
+ {
+ label: "Run check in GitHub Actions",
+ slug: "guides/how-to-run-synthetic-test-github-action",
+ },
+ {
+ label: "Export Metrics to your OTLP Endpoint",
+ slug: "guides/how-to-export-metrics-to-otlp-endpoint",
+ },
+ {
+ label: "How to Add an SVG Status Badge to your GitHub README",
+ slug: "guides/how-to-add-svg-status-badge",
+ },
+ {
+ label: "How to use React Status Widget",
+ slug: "guides/how-to-use-react-widget",
+ },
+ ],
+ },
+ {
+ label: "Reference",
+ items: [
+ {
+ label: "CLI Reference",
+ slug: "reference/cli-reference",
+ },
+ {
+ label: "API Reference",
+ link: "https://api.openstatus.dev/v1",
+ // badge: { text: 'External' },
+ attrs: {
+ target: "_blank",
},
- ],
- },
- ]),
+ },
+ {
+ label: "Incident",
+ slug: "reference/incident",
+ },
+ {
+ label: "HTTP Monitor",
+ slug: "reference/http-monitor",
+ },
+ {
+ label: "TCP Monitor",
+ slug: "reference/tcp-monitor",
+ },
+ {
+ label: "Notification",
+ slug: "reference/notification",
+ },
+ {
+ label: "Status Page",
+ slug: "reference/status-page",
+ },
+ {
+ label: "Status Report",
+ slug: "reference/status-report",
+ },
+ {
+ label: "Subscriber",
+ slug: "reference/subscriber",
+ },
+ {
+ label: "Terraform Provider",
+ slug: "reference/terraform",
+ },
+ ],
+ },
+ ],
+ plugins: [
starlightLlmsTxt({
projectName: "OpenStatus Documentation",
description:
diff --git a/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/grafana.png b/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/grafana.png
new file mode 100644
index 000000000..8b98dbd11
Binary files /dev/null and b/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/grafana.png differ
diff --git a/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/honeycomb.jpg b/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/honeycomb.jpg
new file mode 100644
index 000000000..ce0184809
Binary files /dev/null and b/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/honeycomb.jpg differ
diff --git a/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/newrelic.jpg b/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/newrelic.jpg
new file mode 100644
index 000000000..7e2c0b011
Binary files /dev/null and b/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/newrelic.jpg differ
diff --git a/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/signoz.jpg b/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/signoz.jpg
new file mode 100644
index 000000000..5037fcc99
Binary files /dev/null and b/apps/docs/src/assets/guides/how-to-export-metrics-via-otel/signoz.jpg differ
diff --git a/apps/docs/src/assets/monitor/create-monitor/create-monitor-1.png b/apps/docs/src/assets/tutorial/create-monitor/create-monitor-1.png
similarity index 100%
rename from apps/docs/src/assets/monitor/create-monitor/create-monitor-1.png
rename to apps/docs/src/assets/tutorial/create-monitor/create-monitor-1.png
diff --git a/apps/docs/src/assets/monitor/create-monitor/create-monitor-2.png b/apps/docs/src/assets/tutorial/create-monitor/create-monitor-2.png
similarity index 100%
rename from apps/docs/src/assets/monitor/create-monitor/create-monitor-2.png
rename to apps/docs/src/assets/tutorial/create-monitor/create-monitor-2.png
diff --git a/apps/docs/src/assets/monitor/create-monitor/monitor-overview.png b/apps/docs/src/assets/tutorial/create-monitor/monitor-overview.png
similarity index 100%
rename from apps/docs/src/assets/monitor/create-monitor/monitor-overview.png
rename to apps/docs/src/assets/tutorial/create-monitor/monitor-overview.png
diff --git a/apps/docs/src/assets/tutorial/create-status-page/create-status-page-1.png b/apps/docs/src/assets/tutorial/create-status-page/create-status-page-1.png
new file mode 100644
index 000000000..1ae8b63de
Binary files /dev/null and b/apps/docs/src/assets/tutorial/create-status-page/create-status-page-1.png differ
diff --git a/apps/docs/src/assets/tutorial/create-status-page/create-status-page-2.png b/apps/docs/src/assets/tutorial/create-status-page/create-status-page-2.png
new file mode 100644
index 000000000..f01747f84
Binary files /dev/null and b/apps/docs/src/assets/tutorial/create-status-page/create-status-page-2.png differ
diff --git a/apps/docs/src/assets/tutorial/get-started-with-openstatus-cli/CLI.png b/apps/docs/src/assets/tutorial/get-started-with-openstatus-cli/CLI.png
new file mode 100644
index 000000000..20c6df035
Binary files /dev/null and b/apps/docs/src/assets/tutorial/get-started-with-openstatus-cli/CLI.png differ
diff --git a/apps/docs/src/components/Footer.astro b/apps/docs/src/components/Footer.astro
index 746233cf2..748448c3b 100644
--- a/apps/docs/src/components/Footer.astro
+++ b/apps/docs/src/components/Footer.astro
@@ -15,9 +15,10 @@ import Pagination from "@astrojs/starlight/components/Pagination.astro";
<span>Show your support! Star us on GitHub โญ๏ธ</span>
<a class="github-button" href="https://github.com/openstatusHQ/openstatus" data-color-scheme="no-preference: light; light: light; dark: light;" data-icon="octicon-star" data-size="large" data-show-count="true" aria-label="Star openstatusHQ/openstatus on GitHub">Star</a>
</div>
-
<div class="flex items-center justify-center">
- <img src='https://status.openstatus.dev/badge'>
+ <a href="https://status.openstatus.dev" target="_blank" >
+ <img src='https://status.openstatus.dev/badge/v2?variant=outline'>
+ </a>
</div>
</footer>
diff --git a/apps/docs/src/content/docs/cli/commands/run.mdx b/apps/docs/src/content/docs/cli/commands/run.mdx
deleted file mode 100644
index e4c379e92..000000000
--- a/apps/docs/src/content/docs/cli/commands/run.mdx
+++ /dev/null
@@ -1,33 +0,0 @@
----
-title: run
-description: "How to run a list of synthetic checks in OpenStatus from the command line"
----
-
-### `run` command (aliases: `r`)
-
-Run your synthetics tests.
-
-> openstatus run [options]
-
-Run the synthetic tests defined in the `config.openstatus.yaml`.
-The config file should be in the following format:
-
-```yaml
-tests:
- ids:
- - monitor-id-1
- - monitor-id-2
-```
-
-Usage:
-
-```bash
-$ openstatus [GLOBAL FLAGS] run [COMMAND FLAGS] [ARGUMENTS...]
-```
-
-The following flags are supported:
-
-| Name | Description | Default value | Environment variables |
-|-----------------------------|-----------------------------|:------------------------:|:----------------------:|
-| `--config="โ€ฆ"` | The configuration file | `config.openstatus.yaml` | *none* |
-| `--access-token="โ€ฆ"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
diff --git a/apps/docs/src/content/docs/cli/commands/whoami.mdx b/apps/docs/src/content/docs/cli/commands/whoami.mdx
deleted file mode 100644
index c23eda28c..000000000
--- a/apps/docs/src/content/docs/cli/commands/whoami.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-title: whoami
-description: "How to check the currently authenticated user in OpenStatus with the whoami command"
----
-
-The `whoami` command is used to display the currently authenticated user. This command is useful to check if you are logged in and to see the workspace details.
-
-```
-openstatus whoami [options]
-```
-
-**--access-token, -t**="": OpenStatus API Access Token
diff --git a/apps/docs/src/content/docs/cli/getting-started.mdx b/apps/docs/src/content/docs/cli/getting-started.mdx
deleted file mode 100644
index 38dad48e9..000000000
--- a/apps/docs/src/content/docs/cli/getting-started.mdx
+++ /dev/null
@@ -1,72 +0,0 @@
----
-title: Getting Started
-description: "Get started with OpenStatus CLI and start triggering your synthetic checks from your terminal"
----
-
-import { Image } from 'astro:assets';
-
-import CLI from '../../../assets/cli/CLI.png';
-
- <Image
- src={CLI}
- alt="OpenStatus CLI"
- />
-
-
-
-You can use the OpenStatus CLI to manage and run your monitors. The CLI is a powerful tool that allows you to interact with OpenStatus from your terminal.
-
-## Installation
-
-You can install the OpenStatus CLI using brew.
-
-#### Windows
-```powershell
-iwr instl.sh/openstatushq/cli/windows | iex
-```
-
-#### macOS
-```bash
-brew install openstatusHQ/cli/openstatus --cask
-```
-
-or
-
-
-```bash
-curl -sSL instl.sh/openstatushq/cli/macos | bash
-```
-
-
-
-#### Linux
-```bash
-curl -sSL instl.sh/openstatushq/cli/linux | bash
-```
-
-
-
-Then you can run the following command to verify the installation.
-
-```bash
-openstatus --help
-```
-
-
-## Usage
-
-You need to get an API token to use the CLI. You can get an API key by signing up on the OpenStatus website.
-
-_Settings &rarr; API Token &rarr; Create API token_
-
-You can set the API token using the following command.
-
-```bash
-export OPENSTATUS_API_TOKEN=your-api-token
-```
-
-or you can set the `--access-token` option in the CLI command.
-
-```bash
-openstatus [COMMAND] --access-token your-api-token
-```
diff --git a/apps/docs/src/content/docs/concept/best-practices-status-page.mdx b/apps/docs/src/content/docs/concept/best-practices-status-page.mdx
new file mode 100644
index 000000000..a66bcec72
--- /dev/null
+++ b/apps/docs/src/content/docs/concept/best-practices-status-page.mdx
@@ -0,0 +1,79 @@
+---
+title: Best Practices for Status Pages
+---
+
+
+```
++------------------------------------------------+
+| openstatus Status Page |
++------------------------------------------------+
+| Service Name | Status | Uptime |
++-------------------+--------+-------------------+
+| Web Server | โœ… OK | 99.9% |
+| Database | โœ… OK | 99.8% |
+| API Gateway | โš ๏ธ Degraded | 99.5% |
+| Monitoring | โœ… OK | 100% |
+| Payment Processing| โœ… OK | 99.7% |
++-------------------+--------+-------------------+
+| Incidents: |
+| |
+| - Degraded performance on API Gateway due |
+| to high traffic. Our team is investigating.|
++------------------------------------------------+
+```
+
+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.
+
+
+
+
+## Best Practices for a Status Page
+
+### Maintain Transparency and Honesty
+
+A status page's primary goal is to be a single source of truth. Be upfront about issues, even minor ones. Hiding problems erodes user trust and can lead to more support requests.
+
+- **Communicate Clearly:** Use simple, non-technical language. Users shouldn't need a dictionary to understand what's happening.
+
+- **Be Timely:** Update the page as soon as an incident is confirmed and provide regular updates throughout the resolution process.
+
+### Automate Where Possible
+
+Manual updates during an outage are prone to error and can be slow. Automating your status page can provide more accurate and timely information.
+
+- **Integrate Monitoring Tools:** Connect your internal monitoring and alerting systems to your status page. When a metric crosses a threshold (e.g., high error rate), the status page can automatically be updated.
+
+- **Use an API:** we provide APIs that allow you to programmatically update component statuses and post new incidents.
+
+
+### Provide Detailed Incident Communication
+
+When an incident occurs, provide a detailed and structured narrative.
+
+- **Start with the "What":** State the problem clearly and concisely.
+
+- **Follow with the "Why":** Briefly explain the root cause, if known.
+
+- **Conclude with the "How" and "When":** Explain the steps being taken to resolve the issue and provide an estimated time to resolution.
+
+**Example Incident Update:**
+
+- **Investigating:** "We're currently investigating an issue affecting user logins."
+
+- **Identified:** "We've identified the root cause as a database connection issue and are working on a fix."
+
+- **Monitoring:** "A fix has been deployed, and we're monitoring the system's performance."
+
+- **Resolved:** "The issue has been resolved, and all services are now operational."
+
+
+### Make it Easily Accessible
+
+Your status page should be easy to find.
+
+- **Prominent Link:** Place a link to your status page in your application's footer, on your website, and in your support documentation.
+
+- **Custom Domain:** Use a simple, memorable URL like status.yourcompany.com.
+
+
+Following these practices turns your status page from a passive communication tool into an active driver of customer trust and confidence.
diff --git a/apps/docs/src/content/docs/concept/getting-started.mdx b/apps/docs/src/content/docs/concept/getting-started.mdx
new file mode 100644
index 000000000..223beeb52
--- /dev/null
+++ b/apps/docs/src/content/docs/concept/getting-started.mdx
@@ -0,0 +1,14 @@
+---
+title: Getting Started
+---
+
+
+Hereโ€™s some content to help you get started with the concept behind OpenStatus.
+
+- [Uptime Monitoring](/tutorial/uptime-monitoring)
+
+- [Best Practices for Status Pages](/tutorial/best-practices-status-page)
+
+- [Uptime Monitoring as Code](/tutorial/uptime-monitoring-as-code)
+
+- [Latency vs Response Time](/tutorial/latency-vs-response-time)
diff --git a/apps/docs/src/content/docs/concept/latency-vs-response-time.mdx b/apps/docs/src/content/docs/concept/latency-vs-response-time.mdx
new file mode 100644
index 000000000..1e50f67d2
--- /dev/null
+++ b/apps/docs/src/content/docs/concept/latency-vs-response-time.mdx
@@ -0,0 +1,71 @@
+---
+title: Latency vs Response Time for a request
+---
+
+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.
+
+## What is Latency?
+
+```
+openstatus Network Server (Website)
+ | | |
+ |------- Request ---------->| |
+ | (Timestamp A: Send) | |
+ | |------- Process --------->|
+ | | (Server processing time) |
+ | |<------- Response --------|
+ | | (Timestamp B: Receive) |
+ | | |
+Latency = Timestamp B - Timestamp A
+```
+
+Latency is the time it takes for data to travel from its source to its destination. Think of it as the round-trip time (RTT) for a network packet. This delay is influenced by several factors:
+
+- **Distance:** The physical distance between the client and the server. Data traveling across continents will have higher latency than data traveling within the same city.
+
+- **Network Congestion:** When too much data is on the network, it can slow down transmission, similar to a traffic jam on a highway.
+
+To measure latency, you can monitor endpoints like `/ping` or `/healthcheck` with minimum server processing time.
+
+## What Is Response Time?
+
+```
+ openstatus Network Server
+ | | |
+(Start) |------- Request -------->| |
+(T1) | | |
+ | |--- Processing ----->|
+ | | (Server's work) |
+ | |<-- Response Data ---|
+ | | |
+(End) |<--- (Received) ---------| |
+(T2) | | |
+
+ Response Time = T2 - T1
+```
+
+
+Response time is the total time from the moment a user's request is sent until the moment the first byte of the server's response is received. It includes both the network latency and the server's processing time.
+
+Response time = Network Latency + Server Processing Time
+
+The server processing time is the duration the server spends on tasks like:
+
+- Executing database queries.
+- Running application logic.
+- Generating the HTML or JSON response.
+
+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.
+
+
+## Why the Distinction Matters for Uptime Monitoring
+
+Understanding the difference between these two metrics is crucial for diagnosing performance issues.
+
+- If your monitoring shows a **high response time but low latency**, the problem is likely with your server's performance. You should investigate your application's code, database queries, and server resources.
+
+- If both your **latency and response time** are high, the issue is likely network-related. This could be due to a poor connection between the monitoring location and your server, or a broader network issue.
+
+- **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.
+
+By monitoring both metrics, you can quickly pinpoint whether a performance slowdown is caused by your application or by the network.
diff --git a/apps/docs/src/content/docs/concept/uptime-monitoring-as-code.mdx b/apps/docs/src/content/docs/concept/uptime-monitoring-as-code.mdx
new file mode 100644
index 000000000..c05510832
--- /dev/null
+++ b/apps/docs/src/content/docs/concept/uptime-monitoring-as-code.mdx
@@ -0,0 +1,90 @@
+---
+title: Uptime Monitoring as Code
+---
+import { Code } from '@astrojs/starlight/components';
+export const code = `
+# yaml-language-server: $schema=https://www.openstatus.dev/schema.json
+uptime-monitor:
+ name: "Uptime Monitor"
+ description: "Uptime monitoring example"
+ frequency: "10m"
+ active: true
+ regions:
+ - iad
+ - ams
+ - syd
+ - jnb
+ - gru
+ retry: 3
+ kind: http
+ request:
+ url: https://openstat.us
+ method: GET
+ headers:
+ User-Agent: OpenStatus
+ assertions:
+ - kind: statusCode
+ compare: eq
+ target: 200
+
+graphql-monitor:
+ name: "Graphql"
+ description: "GitHub GraphQL API"
+ frequency: "10m"
+ active: true
+ regions:
+ - iad
+ - ams
+ - syd
+ - jnb
+ - gru
+ retry: 3
+ kind: http
+ request:
+ url: https://api.github.com/graphql
+ method: POST
+ headers:
+ User-Agent: OpenStatus
+ Authorization: Bearer YOUR_TOKEN_HERE
+ body: |
+ {
+ "query": "query { viewer { login }}"
+ }
+`
+
+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.
+
+
+## Why Use Uptime Monitoring as Code?
+
+This approach offers significant advantages:
+
+- **Version Control:** By defining your monitors in a YAML file, you can track every change, rollback to previous versions, and see who made which modifications using tools like Git. This is crucial for auditing and troubleshooting.
+
+- **Automation and Consistency:** Your monitoring setup can be part of your automated deployment pipeline. When you deploy a new service, its monitors are created automatically, ensuring consistency across your entire infrastructure. This eliminates the risk of forgetting to set up monitoring for a new service.
+
+- **Collaboration:** A code-based approach simplifies collaboration among teams. A developer can create a new monitor definition in the YAML file and submit it for peer review, just as they would with any other code change. This promotes a shared understanding of your system's health.
+
+- **Scalability:** Manually setting up hundreds of monitors is a nightmare. With a code-based approach, you can programmatically generate configurations for a large number of services, making it easy to scale your monitoring as your infrastructure grows.
+
+- **Simplified Auditing:** Since the entire configuration is in a file, it's easy to see the current state of your monitors at a glance. You don't have to navigate through multiple screens in a web UI.
+
+
+## How It Works with openstatus
+
+ We offer the use ofa simple, human-readable YAML file to define all uptime monitors. This file serves as the single source of truth for your monitoring setup. You define each monitor with its URL, expected status code, and other parameters.
+
+Hereโ€™s an example of what your `openstatus.yaml` file might look like:
+
+<Code code={code} lang="yaml" title='openstatus.yaml' />
+
+### Making Changes with the CLI
+
+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.
+
+**Common CLI Commands:**
+
+- `openstatus monitors apply`: Applies the changes defined in your `openstatus.yaml` file.
+- `openstatus monitors import`: Import the monitors from your dashboard to a new `openstatus.yaml` file.
+
+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.
diff --git a/apps/docs/src/content/docs/concept/uptime-monitoring.mdx b/apps/docs/src/content/docs/concept/uptime-monitoring.mdx
new file mode 100644
index 000000000..be6fc3aea
--- /dev/null
+++ b/apps/docs/src/content/docs/concept/uptime-monitoring.mdx
@@ -0,0 +1,93 @@
+---
+title: About Uptime Monitoring
+---
+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.
+
+
+```
++----------------+
+| Service to be |
+| Monitored |
++----------------+
+ โ–ฒ
+ |
+ | (Network Latency)
+ |
++-----+-------+ +-----+-------+ +-----+-------+
+| Monitoring | | Monitoring | | Monitoring |
+| Node (USA) | | Node (EU) | | Node (Asia) |
++-----+-------+ +-----+-------+ +-----+-------+
+ | | |
+ |---------------|-----------------|
+ โ–ผ โ–ผ โ–ผ
++------------------------------------------------+
+| Global Uptime Monitoring Service |
+| |
+| - Sends automated requests (e.g., pings or |
+| HTTP checks) from all nodes at set intervals |
+| - Records response time and success/failure |
+| - Compares results from different nodes |
+| - If a failure or a slow response is detected, |
+| it triggers an alert. |
++------------------------------------------------+
+ |
+ | (Alerts: Email, SMS, Slack, etc.) ๐Ÿ””
+ |
++-----+-----+
+| Your Team |
++-----------+
+```
+
+
+## Key Concepts
+
+- **Downtime**: The period when a service is unavailable or not functioning as expected. It can be caused by server failures, network issues, software bugs, or even cyberattacks.
+
+- **Uptime**: The percentage of time a service is available and operational. A high uptime percentage (e.g., 99.9% or "three nines") indicates reliability.
+
+- **Alerting**: The system of notifying a team or individual when downtime is detected. Alerts can be sent via email, SMS, Slack, or other communication channels.
+
+## Why Uptime Monitoring is Crucial
+
+- **Business Continuity**: Downtime can lead to significant financial losses, damage to reputation, and loss of customer trust. Uptime monitoring helps you address issues quickly, ensuring your services are always available to your users.
+
+- **Performance Insight**: Monitoring tools often provide data on latency and response times, giving you insights into your service's performance beyond just availability. This can help you optimize your infrastructure and user experience.
+
+- **Proactive Problem Solving**: Instead of waiting for a customer to report an issue, uptime monitoring allows you to be the first to know about it. This enables you to troubleshoot and resolve problems before they escalate.
+
+## How it Works
+
+Uptime monitoring typically involves a monitoring agent that periodically sends a request (like an HTTP GET request) to your service.
+
+- If the service responds with a successful status code (e.g., 200 OK), it's considered up.
+
+- If the service returns an error code, a timeout, or no response, the agent will perform a re-check from a different location to confirm the outage. This helps prevent false alarms caused by temporary network glitches.
+
+- Upon confirmation, the system triggers an alert, notifying the relevant team members. The monitoring system will continue to check the service until it's back online, at which point a recovery alert is often sent.
+
+Common types of checks include:
+
+- **HTTP/HTTPS checks:** Verify a website is accessible and returns a valid response.
+- **TCP checks:** Confirm a server is reachable on the network.
+
+
+
+## Planning an Uptime Monitoring System
+
+When planning your own uptime monitoring system, consider the following:
+
+1. Define What to Monitor: Identify all critical services, websites, APIs, and servers that need to be monitored. Prioritize based on business impact.
+
+2. Select a Monitoring Tool: Choose a tool that fits your needs. Options range from simple free services to complex enterprise-level platforms. Look for features like:
+
+ - **Multiple locations:** Checks from various geographic regions to ensure global availability.
+
+ - **Customizable alerting:** Set up different alert thresholds and notification methods.
+
+ - **Reporting and dashboards:** Visualize uptime history, performance metrics, and incident reports.
+
+ - **Integrations:** Connect with your existing tools like Slack, PagerDuty, or email.
+
+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.
+
+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.
diff --git a/apps/docs/src/content/docs/guides/getting-started.mdx b/apps/docs/src/content/docs/guides/getting-started.mdx
new file mode 100644
index 000000000..85367e2dc
--- /dev/null
+++ b/apps/docs/src/content/docs/guides/getting-started.mdx
@@ -0,0 +1,20 @@
+---
+title: Introduction
+description: Guides to get started with OpenStatus guides
+sidebar:
+ label: Introduction
+ order: 1
+---
+
+Here's some guides for the getting started with OpenStatus.
+
+
+- [How to monitor your MCP Server using OpenStatus](/guides/how-to-monitor-mcp-server/)
+
+- [How to run synthetic tests in your GitHub Actions](/guides/how-to-run-synthetic-test-github-action/)
+
+- [Export Metrics to your OTLP endpoint](/guides/how-to-export-metrics-to-otlp-endpoint)
+
+- [How to Add an SVG Status Badge to your GitHub README](/guides/how-to-add-svg-status-badge)
+
+- [How to use React Status Widget](/guides/how-to-use-react-widget)
diff --git a/apps/docs/src/content/docs/guides/how-deploy-checker-koyeb.mdx b/apps/docs/src/content/docs/guides/how-deploy-checker-koyeb.mdx
deleted file mode 100644
index 12d1b8b17..000000000
--- a/apps/docs/src/content/docs/guides/how-deploy-checker-koyeb.mdx
+++ /dev/null
@@ -1,69 +0,0 @@
----
-title: How to deploy your own checker on Koyeb
-description: Learn how to deploy our checker on Koyeb.
-sidebar:
- label: Deploy our probe on Koyeb
----
-import { Image } from 'astro:assets';
-
-import Koyeb1 from '../../../assets/guides/how-deploy-checker-koyeb/koyeb-1.png';
-import Koyeb2 from '../../../assets/guides/how-deploy-checker-koyeb/koyeb-2.png';
-import Koyeb3 from '../../../assets/guides/how-deploy-checker-koyeb/koyeb-3.png';
-
-
-## Introduction
-
-You need a koeyb account to deploy our checker on Koyeb. If you don't have one, you can create one [here](https://app.koyeb.com/).
-
-## Deploying the checker
-
-1. Go to the [Koyeb dashboard](https://app.koyeb.com/).
-
-2. Click on the `Create Service` button.
-
-3. Select the `Docker` option.
-
-
- <Image
- src={Koyeb1}
- alt="Koyeb"
- />
-
-
-4. In the `Image` field, enter `ghcr.io/openstatushq/checker:latest`.
-
-
- <Image
- src={Koyeb2}
- alt="Koyeb"
- />
-
-5. Click on the `Next` button.
-
-6. Fill the following settings
-
-You should set the following environment variables
-- `CLOUD_PROVIDER` : Koyeb
-- `REGION` : The koyeb region where you want to deploy your checker
-- `CRON_SECRET` : A secret key to secure your endpoint to avoid unauthorized access
-
- <Image
- src={Koyeb3}
- alt="Koyeb"
- />
-
-## Calling your probe
-
-Once your checker is deployed, you can call it using the following command:
-
-```bash
-curl --request POST \
- --url https://YOUR_KOYEB_URL.koyeb.app/ping/KOYEB_REGION \
- --header 'Authorization: Basic test' \
- --header 'Content-Type: application/json' \
- --data '{
- "url": "https://www.openstatus.dev",
- "method": "GET"
-}'
-```
-
diff --git a/apps/docs/src/content/docs/guides/how-to-add-svg-status-badge.mdx b/apps/docs/src/content/docs/guides/how-to-add-svg-status-badge.mdx
new file mode 100644
index 000000000..38362822e
--- /dev/null
+++ b/apps/docs/src/content/docs/guides/how-to-add-svg-status-badge.mdx
@@ -0,0 +1,78 @@
+---
+title: How to Add an SVG Status Badge to your GitHub README
+---
+
+You want to add an SVG status badge to your GitHub README?
+
+### PNG Badge
+
+```html
+<img src='https://[slug].openstatus.dev/badge'>
+```
+
+This will return a PNG image with the status of your page. It will look like this:
+<img src='https://status.openstatus.dev/badge' />
+
+You can customize the theme by adding `?theme=dark` and the size of it by adding `?size=lg`.
+
+Supported themes:
+- `dark`
+- `light` (default)
+
+Supported sizes:
+- `sm` (default)
+- `md`
+- `lg`
+- `xl`
+
+It will display the following labels based on the current status of the status page:
+
+```
+Operational
+Degraded
+Outage
+Incident
+Maintenance
+Unknown
+```
+
+### SVG Badge (v2)
+
+```html
+<img src='https://[slug].openstatus.dev/badge/v2'>
+```
+
+This will return a PNG image with the status of your page. It will look like this:
+<img src='https://status.openstatus.dev/badge/v2' />
+
+You can customize the theme by adding `?theme=dark`, the size of it by adding `?size=lg` and the variant `?variant=outline` - use what fits best to you!
+
+Supported themes:
+- `light` (default)
+- `dark`
+
+Supported sizes:
+- `sm` (default)
+- `md`
+- `lg`
+- `xl`
+
+Supported variants:
+- `default` (default)
+- `outline`
+
+The **outline** variant simply adds a slightly rounded border to the svg `rect`. It mainly can be used for GitHub README or Markdown where styling is not supported.
+
+Compared to the PNG badge, we let you define the `border` and `border-radius` of the SVG badge and the font is mono.
+
+It will display the following labels based on the current status of the status page:
+
+```
+All Systems Operational
+Degraded Performance
+Partial Outage
+Major Outage
+Ongoing Incident
+Under Maintenance
+Unknown
+```
diff --git a/apps/docs/src/content/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx b/apps/docs/src/content/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx
new file mode 100644
index 000000000..d67eafd66
--- /dev/null
+++ b/apps/docs/src/content/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx
@@ -0,0 +1,63 @@
+---
+title: How to Export Metrics to your OTLP endpoint
+---
+import { Image } from 'astro:assets';
+
+import grafana from '../../../assets/guides/how-to-export-metrics-via-otel/grafana.png';
+import newrelic from '../../../assets/guides/how-to-export-metrics-via-otel/newrelic.jpg';
+import signoz from '../../../assets/guides/how-to-export-metrics-via-otel/signoz.jpg';
+import honeycomb from '../../../assets/guides/how-to-export-metrics-via-otel/honeycomb.jpg';
+
+
+At openstatus, we believe you should be able to export your metrics to your OTLP endpoint without having to change your existing monitoring platform.
+
+
+
+## Export your metrics to your OTLP endpoint
+
+In your monitoring platform find the configuration section for metrics export.
+
+Right now we only support HTTP OTLP endpoint.
+
+In your `openstatus.yaml` file, add the following configuration:
+
+```yaml
+openTelemetry:
+ endpoint: http://your-otel-endpoint:4318/v1/metrics
+ headers:
+ Authorization: Bearer your-token
+```
+
+After every check we will send you the metrics to your monitoring stack.
+
+
+### Grafana
+
+ <Image
+ src={grafana}
+ alt="openstatus metrics in grafana"
+ />
+
+### honeycomb
+
+ <Image
+ src={honeycomb}
+ alt="openstatus metrics in honeycomb"
+ />
+
+
+### New Relic
+
+ <Image
+ src={newrelic}
+ alt="openstatus metrics in new-relic"
+ />
+
+
+
+### signoz
+
+ <Image
+ src={signoz}
+ alt="openstatus metrics in signoz"
+ />
diff --git a/apps/docs/src/content/docs/guides/how-to-use-react-widget.mdx b/apps/docs/src/content/docs/guides/how-to-use-react-widget.mdx
new file mode 100644
index 000000000..967a921e2
--- /dev/null
+++ b/apps/docs/src/content/docs/guides/how-to-use-react-widget.mdx
@@ -0,0 +1,72 @@
+---
+title: How to Use OpenStatus React Widget
+---
+
+Install the [npm](https://www.npmjs.com/package/@openstatus/react) package:
+
+```bash
+npm install @openstatus/react
+```
+
+## React Server Component
+
+```tsx
+import { StatusWidget } from "@openstatus/react";
+
+export function Page() {
+ return <StatusWidget slug="status" />;
+}
+```
+
+It will automatically attach the slug to the href to allow the user to open a
+new tab on click to `https://slug.openstatus.dev`. If you want to redirect him
+to a specific page, use the `href` property, like so:
+
+```tsx
+<StatusWidget slug="documenso" href="https://status.documenso.com" />
+```
+
+> `StatusWidget` is an **async function** and will only work with RSC. Using it
+> within a dead simple React App will not work.
+
+### Styling
+
+#### With tailwindcss
+
+```ts
+// tailwind.config.js
+module.exports = {
+ content: [
+ "./app/**/*.{tsx,ts,mdx,md}",
+ "./node_modules/@openstatus/react/**/*.{js,ts,jsx,tsx}",
+ ],
+ theme: {
+ extend: {},
+ },
+ plugins: [],
+};
+```
+
+#### Without tailwindcss
+
+```tsx
+// app/layout.tsx
+import "@openstatus/react/dist/styles.css";
+```
+
+## Typed fetch function
+
+```tsx
+import { getStatus } from "@openstatus/react";
+
+// React Server Component
+async function CustomStatusWidget() {
+ const res = await getStatus("slug");
+ // ^StatusResponse = { status: Status }
+
+ const { status } = res;
+ // ^Status = "unknown" | "operational" | "degraded_performance" | "partial_outage" | "major_outage" | "under_maintenance" | "incident"
+
+ return <div>{/* customize */}</div>;
+}
+```
diff --git a/apps/docs/src/content/docs/guides/introduction.mdx b/apps/docs/src/content/docs/guides/introduction.mdx
deleted file mode 100644
index f1b0e341c..000000000
--- a/apps/docs/src/content/docs/guides/introduction.mdx
+++ /dev/null
@@ -1,17 +0,0 @@
----
-title: Introduction
-description: Guides to get started with OpenStatus
-sidebar:
- label: Introduction
- order: 1
----
-
-Here's some content for the getting started with OpenStatus.
-
-- [How to deploy your own probe to Koyeb](/guides/how-deploy-checker-koyeb/)
-
-- [Deploy your own Status Page to Cloudflare Pages](/guides/how-deploy-status-page-cf-pages)
-
-- [How to monitor your MCP Server using OpenStatus](/guides/how-to-monitor-mcp-server/)
-
-- [How to run synthetic tests in your GitHub Actions](/guides/how-to-run-synthetic-test-github-action/)
diff --git a/apps/docs/src/content/docs/index.mdx b/apps/docs/src/content/docs/index.mdx
index efe1f338f..f6f485512 100644
--- a/apps/docs/src/content/docs/index.mdx
+++ b/apps/docs/src/content/docs/index.mdx
@@ -5,42 +5,31 @@ template: doc
topic: docs
next: false
hero:
- title: Welcome to OpenStatus
- tagline: Explore our documentation to get started with OpenStatus and start monitoring your services.
+ title: Welcome to openstatus
+ tagline: Explore our documentation to get started with openstatus and start monitoring your services.
---
import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
import "../../custom.css"
-### What is OpenStatus?
+### What is openstatus?
-[OpenStatus](https://www.openstatus.dev) is an open-source synthetic monitoring tool that helps you monitor the availability and performance of your website, API, servers, or anything that can be monitored from various locations around the world.
+[openstatus](https://www.openstatus.dev) is an open-source synthetic monitoring tool that helps you monitor the availability and performance of your website, API, servers, or anything that can be monitored from various locations around the world.
-We also provide beautiful [status pages](/status-page/overview) to keep your users informed about the status of your services.
+We also provide [status pages](/tutorial/how-to-create-status-page) to keep your users informed about the status of your services.
#### Monitoring as Code
-We provide a [CLI](/cli/getting-started) to manage your monitors as code.
+We provide a [CLI](/tutorial/get-started-with-openstatus-cli) to manage your monitors as code.
### New to OpenStatus?
<CardGrid >
- <Card title="Synthetic Monitoring" icon="open-book">
- Learn how to <a href="/monitoring/create-monitor">create</a> your first monitor with OpenStatus.
- </Card>
- <Card title="Guides " icon="rocket">
- Read our <a href="guides/introduction/">guides</a> to discover what you can do with OpenStatus
- </Card>
- <Card title="CLI" icon="seti:shell">
- Learn more about our [CLI](/cli/getting-started) to manage and run your synthetic check.
- </Card>
- <Card title="API Reference" icon="puzzle">
- Use our <a href="https://api.openstatus.dev/v1">API</a> to build amazing things on top of OpenStatus
- </Card>
- <Card title="Open Source" icon="seti:github">
- Checkout our [GitHub repository](https://www.github.com/openstatushq/openstatus) to contribute or report issues.
- </Card>
+ <LinkCard title="Concepts" href="/concept/getting-started/" description="Read about the concept behind OpenStatus" />
+ <LinkCard title="Tutorials" href="/tutorial/getting-started/" description="Read our tutorials to learn how to use OpenStatus" />
+ <LinkCard title="Guides" href="/guides/getting-started/" description="Some useful guides about openstatus" />
+ <LinkCard title="Help" href="/help/support/" description="Need help?" />
</CardGrid>
diff --git a/apps/docs/src/content/docs/reference.mdx b/apps/docs/src/content/docs/reference.mdx
new file mode 100644
index 000000000..f391f5758
--- /dev/null
+++ b/apps/docs/src/content/docs/reference.mdx
@@ -0,0 +1,4 @@
+---
+title: About this project
+description: Learn more about the project Iโ€™m working on.
+---
diff --git a/apps/docs/src/content/docs/cli/commands/monitors.mdx b/apps/docs/src/content/docs/reference/cli-reference.mdx
similarity index 71%
rename from apps/docs/src/content/docs/cli/commands/monitors.mdx
rename to apps/docs/src/content/docs/reference/cli-reference.mdx
index 24aa209d1..469b521a5 100644
--- a/apps/docs/src/content/docs/cli/commands/monitors.mdx
+++ b/apps/docs/src/content/docs/reference/cli-reference.mdx
@@ -1,20 +1,28 @@
---
-title: monitors
-description: "Manage your monitors in OpenStatus from the command line"
+title: CLI Reference
---
-x
-### `monitors` command
+## CLI interface - openstatus
+
+OpenStatus is a command line interface for managing your monitors and triggering your synthetics tests.
+
+This is OpenStatus Command Line Interface, the OpenStatus.dev CLI.
+
+Usage:
-The monitors command is used to manage your monitors. You can import, update, delete, trigger, view and list your monitors using this command.
+```bash
+$ openstatus [COMMAND] [COMMAND FLAGS] [ARGUMENTS...]
+```
+### `monitors` command
+
+Manage your monitors.
Usage:
```bash
$ openstatus [GLOBAL FLAGS] monitors [ARGUMENTS...]
```
-**--access-token, -t**="": OpenStatus API Access Token
### `monitors apply` subcommand
@@ -24,10 +32,6 @@ Create or update monitors.
Creates or updates monitors according to the OpenStatus configuration file.
-You can find some examples in the OpenStatus Template repository:
-
-[https://github.com/openstatusHQ/cli-template/](https://github.com/openstatusHQ/cli-template/)
-
Usage:
```bash
@@ -124,3 +128,44 @@ The following flags are supported:
| Name | Description | Default value | Environment variables |
|-----------------------------|-----------------------------|:-------------:|:----------------------:|
| `--access-token="โ€ฆ"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
+
+### `run` command (aliases: `r`)
+
+Run your synthetics tests.
+
+> openstatus run [options]
+
+Run the synthetic tests defined in the config.openstatus.yaml.
+
+Usage:
+
+```bash
+$ openstatus [GLOBAL FLAGS] run [COMMAND FLAGS] [ARGUMENTS...]
+```
+
+The following flags are supported:
+
+| Name | Description | Default value | Environment variables |
+|-----------------------------|-----------------------------|:------------------------:|:----------------------:|
+| `--config="โ€ฆ"` | The configuration file | `config.openstatus.yaml` | *none* |
+| `--access-token="โ€ฆ"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
+
+### `whoami` command (aliases: `w`)
+
+Get your workspace information.
+
+> openstatus whoami [options]
+
+Get your current workspace information, display the workspace name, slug, and plan.
+
+Usage:
+
+```bash
+$ openstatus [GLOBAL FLAGS] whoami [COMMAND FLAGS] [ARGUMENTS...]
+```
+
+The following flags are supported:
+
+| Name | Description | Default value | Environment variables |
+|-----------------------------|-----------------------------|:-------------:|:----------------------:|
+| `--access-token="โ€ฆ"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |
diff --git a/apps/docs/src/content/docs/reference/http-monitor.mdx b/apps/docs/src/content/docs/reference/http-monitor.mdx
new file mode 100644
index 000000000..68cdcd988
--- /dev/null
+++ b/apps/docs/src/content/docs/reference/http-monitor.mdx
@@ -0,0 +1,144 @@
+---
+title: HTTP Monitor
+---
+
+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.
+
+## Configuration
+
+### URL
+
+The url of the HTTP endpoint you want to monitor e.g `https://openstat.us`
+
+### Methods
+
+The HTTP method you want to use to monitor the endpoint.
+- `GET`
+- `POST`
+- `PUT`
+- `DELETE`
+- `HEAD`
+- `OPTIONS`
+- `PATCH`
+- `TRACE`
+
+### Body
+
+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`.
+Example:
+- `{ "key": "value" }`
+- `data:image/jpeg;base64,/9j...`
+### Headers
+
+The headers you want to send with the HTTP request
+
+Example:
+- `"Content-Type": "application/json"`
+- `'Content-Type: application/octet-stream'`
+
+### Regions
+
+The regions where we are triggering the HTTP request.
+
+__Africa__
+
+- Johannesburg, South Africa ๐Ÿ‡ฟ๐Ÿ‡ฆ (free)
+
+__Asia__
+
+- Hong Kong, Hong Kong ๐Ÿ‡ญ๐Ÿ‡ฐ (free)
+- Mumbai, India ๐Ÿ‡ฎ๐Ÿ‡ณ
+- Singapore, Singapore ๐Ÿ‡ธ๐Ÿ‡ฌ
+- Tokyo, Japan ๐Ÿ‡ฏ๐Ÿ‡ต
+
+__Europe__
+
+- Amsterdam, Netherlands ๐Ÿ‡ณ๐Ÿ‡ฑ (free)
+- Bucharest, Romania ๐Ÿ‡ท๐Ÿ‡ด
+- Frankfurt, Germany ๐Ÿ‡ฉ๐Ÿ‡ช
+- London, United Kingdom ๐Ÿ‡ฌ๐Ÿ‡ง
+- Madrid, Spain ๐Ÿ‡ช๐Ÿ‡ธ
+- Paris, France ๐Ÿ‡ซ๐Ÿ‡ท
+- Stockholm, Sweden ๐Ÿ‡ธ๐Ÿ‡ช
+- Warsaw, Poland ๐Ÿ‡ต๐Ÿ‡ฑ
+
+__North America__
+
+- Ashburn, Virginia, USA ๐Ÿ‡บ๐Ÿ‡ธ (free)
+- Atlanta, Georgia, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Boston, Massachusetts, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Chicago, Illinois, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Dallas, Texas, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Denver, Colorado, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Guadalajara, Mexico ๐Ÿ‡ฒ๐Ÿ‡ฝ
+- Los Angeles, California, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Miami, Florida, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Montreal, Canada ๐Ÿ‡จ๐Ÿ‡ฆ
+- Phoenix, Arizona, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Queretaro, Mexico ๐Ÿ‡ฒ๐Ÿ‡ฝ
+- Seattle, Washington, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- San Jose, California, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Toronto, Canada ๐Ÿ‡จ๐Ÿ‡ฆ
+
+__South America__
+
+- Bogota, Colombia ๐Ÿ‡จ๐Ÿ‡ด
+- Buenos Aires, Argentina ๐Ÿ‡ฆ๐Ÿ‡ท
+- Rio de Janeiro, Brazil ๐Ÿ‡ง๐Ÿ‡ท
+- Sao Paulo, Brazil ๐Ÿ‡ง๐Ÿ‡ท (free)
+- Santiago, Chile ๐Ÿ‡จ๐Ÿ‡ฑ
+
+__Oceania__
+
+- Sydney, Australia ๐Ÿ‡ฆ๐Ÿ‡บ (free)
+
+### Frequency
+
+The check interval, we support the following frequencies:
+- 30 seconds
+- 1 minute
+- 5 minutes
+- 10 minutes
+- 30 minutes
+- 1 hour
+
+### Response Time Thresholds
+#### Timeout
+The timeout for the HTTP request, default is `45 seconds`
+#### Degraded
+The duration for which the HTTP request is considered degraded.
+
+### Retry
+The number of retries for the HTTP request. For example: `3`
+
+### Assertions
+#### Body assertions
+Validate the body of the response. The comparisons are:
+- Contains
+- Not Contains
+- Equal
+- Not Equal
+- Empty
+
+#### Status code assertions
+Validate the status code of the response. The comparisons are:
+- Equal
+- Not Equal
+- Greater Than
+- Greater Than or Equal
+- Less Than
+- Less Than or Equal
+
+#### Headers assertions
+Validate the headers of the reponse. The comparisons are:
+- Contains
+- Not Contains
+- Equal
+- Not Equal
+- Empty
+
+### OpenTelemetry
+#### OTPL Endpoint
+The endpoint we use to export the metrics. We only support HTTP endpoint.
+#### OTLP Headers
+The headers we use to export the metrics to your otlp endpoint.
diff --git a/apps/docs/src/content/docs/reference/incident.mdx b/apps/docs/src/content/docs/reference/incident.mdx
new file mode 100644
index 000000000..2849787e3
--- /dev/null
+++ b/apps/docs/src/content/docs/reference/incident.mdx
@@ -0,0 +1,7 @@
+---
+title: Incident
+---
+
+An incident is a problem related to a monitor. They are created automatically when a monitor fails.
+
+At least 50% must have failed to trigger the incident.
diff --git a/apps/docs/src/content/docs/reference/notification.mdx b/apps/docs/src/content/docs/reference/notification.mdx
new file mode 100644
index 000000000..77de11c8c
--- /dev/null
+++ b/apps/docs/src/content/docs/reference/notification.mdx
@@ -0,0 +1,120 @@
+---
+title: Notification
+---
+
+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.
+
+
+## Notification Channels:
+
+### Slack
+
+Require a [Slack incoming webhook](https://api.slack.com/incoming-webhooks)
+
+### Email
+
+Require an email address
+
+### Discord
+
+Require a [discord webhook](https://support.discord.com/hc/en-us/articles/228383668
+) e.g. `https://discordapp.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz1234567890`
+
+### SMS
+
+Require a phone number
+
+### Webhook
+
+- URL (require)
+- Headers (optional)
+
+#### Notification Payloads
+
+##### Payload for Monitor Recovery
+
+```json
+{
+ "monitor": {
+ "id": 1,
+ "name": "test",
+ "url": "http://openstat.us"
+ },
+ "cronTimestamp": 1744023705307,
+ "status": "recovered",
+ "statusCode": 200,
+ "latency": 1337
+}
+```
+
+
+Fields Explanation:
+- monitor: Contains details about the monitor.
+ - id: Unique identifier for the monitor.
+ - name: Name of the monitor.
+ - url: The URL being monitored.
+- cronTimestamp: The timestamp when the check was executed, in milliseconds since epoch.
+- status: Indicates the current status of the monitor (in this case, "recovered").
+- statusCode: The HTTP status code returned by the monitored service.
+- latency: The time taken to complete the check, in milliseconds.
+
+
+##### Payload for Monitor Failure
+
+```json
+{
+ "monitor": {
+ "id": 1,
+ "name": "test",
+ "url": "http://openstat.us"
+ },
+ "cronTimestamp": 1744023705307,
+ "status": "error",
+ "errorMessage": "Connection refused"
+}
+```
+
+Fields Explanation:
+
+- monitor: Contains details about the monitor.
+ - id: Unique identifier for the monitor.
+ - name: Name of the monitor.
+ - url: The URL being monitored.
+- cronTimestamp: The timestamp when the check was executed, in milliseconds since epoch.
+- status: Indicates the current status of the monitor (in this case, "error").
+- errorMessage: A description of the error encountered during the check.
+
+
+#### Zod Schema
+
+
+```ts
+import { z } from "zod";
+
+export const PayloadSchema = z.object({
+ monitor: z.object({
+ id: z.number(),
+ name: z.string(),
+ url: z.string(),
+ }),
+ cronTimestamp: z.number(),
+ status: z.enum(["degraded", "error", "recovered"]),
+ statusCode: z.number().optional(),
+ latency: z.number().optional(),
+ errorMessage: z.string().optional(),
+});
+````
+
+### OpsGenie
+
+- API key from OpsGenie (required)
+
+### PagerDuty
+
+Follow the step in PagerDuty workflow
+
+### Ntfy
+
+- Ntfy topic (required)
+- Custom server url (optional)
+- bearer token (optional)
diff --git a/apps/docs/src/content/docs/reference/status-page.mdx b/apps/docs/src/content/docs/reference/status-page.mdx
new file mode 100644
index 000000000..3ef5f2cdf
--- /dev/null
+++ b/apps/docs/src/content/docs/reference/status-page.mdx
@@ -0,0 +1,23 @@
+---
+title: Status Page
+---
+
+A status page is a web page that displays the current status of a service or system.
+
+## Configuration
+
+### Slug
+
+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`
+
+### Custom Domain
+
+You can configure a custom domain for your status page. e.g `status.example.com` => `https://status.example.com`
+
+### Password
+
+You can add a password for your status page.
+
+### Favicon
+
+You can add a favicon for your status page.
diff --git a/apps/docs/src/content/docs/reference/status-report.mdx b/apps/docs/src/content/docs/reference/status-report.mdx
new file mode 100644
index 000000000..e2ee9344e
--- /dev/null
+++ b/apps/docs/src/content/docs/reference/status-report.mdx
@@ -0,0 +1,25 @@
+---
+title: Status Report
+---
+
+A status report is an event of an incident.
+
+
+## Configuration
+
+### Status
+
+The status of an incident can be:
+
+- `investigating`
+- `identified`
+- `monitoring`
+- `resolved`
+
+### Date
+
+The date of the status report
+
+### Message
+
+The message of the status report
diff --git a/apps/docs/src/content/docs/reference/subscriber.mdx b/apps/docs/src/content/docs/reference/subscriber.mdx
new file mode 100644
index 000000000..4468ea642
--- /dev/null
+++ b/apps/docs/src/content/docs/reference/subscriber.mdx
@@ -0,0 +1,7 @@
+---
+title: Subscriber
+---
+
+A subscriber is a user who receives notifications about incidents.
+
+They have to subscribe to update from your status page.
diff --git a/apps/docs/src/content/docs/reference/tcp-monitor.mdx b/apps/docs/src/content/docs/reference/tcp-monitor.mdx
new file mode 100644
index 000000000..053cbfa6d
--- /dev/null
+++ b/apps/docs/src/content/docs/reference/tcp-monitor.mdx
@@ -0,0 +1,93 @@
+---
+title: TCP Monitor
+---
+
+
+A TCP Monitor is a component that allows you to monitor the status of your services.
+
+## Configuration
+
+### URI
+
+The url of the endpoint you want to monitor e.g `openstat.us:443`
+
+### Regions
+
+The regions where we are triggering the HTTP request.
+
+__Africa__
+
+- Johannesburg, South Africa ๐Ÿ‡ฟ๐Ÿ‡ฆ (free)
+
+__Asia__
+
+- Hong Kong, Hong Kong ๐Ÿ‡ญ๐Ÿ‡ฐ (free)
+- Mumbai, India ๐Ÿ‡ฎ๐Ÿ‡ณ
+- Singapore, Singapore ๐Ÿ‡ธ๐Ÿ‡ฌ
+- Tokyo, Japan ๐Ÿ‡ฏ๐Ÿ‡ต
+
+__Europe__
+
+- Amsterdam, Netherlands ๐Ÿ‡ณ๐Ÿ‡ฑ (free)
+- Bucharest, Romania ๐Ÿ‡ท๐Ÿ‡ด
+- Frankfurt, Germany ๐Ÿ‡ฉ๐Ÿ‡ช
+- London, United Kingdom ๐Ÿ‡ฌ๐Ÿ‡ง
+- Madrid, Spain ๐Ÿ‡ช๐Ÿ‡ธ
+- Paris, France ๐Ÿ‡ซ๐Ÿ‡ท
+- Stockholm, Sweden ๐Ÿ‡ธ๐Ÿ‡ช
+- Warsaw, Poland ๐Ÿ‡ต๐Ÿ‡ฑ
+
+__North America__
+
+- Ashburn, Virginia, USA ๐Ÿ‡บ๐Ÿ‡ธ (free)
+- Atlanta, Georgia, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Boston, Massachusetts, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Chicago, Illinois, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Dallas, Texas, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Denver, Colorado, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Guadalajara, Mexico ๐Ÿ‡ฒ๐Ÿ‡ฝ
+- Los Angeles, California, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Miami, Florida, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Montreal, Canada ๐Ÿ‡จ๐Ÿ‡ฆ
+- Phoenix, Arizona, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Queretaro, Mexico ๐Ÿ‡ฒ๐Ÿ‡ฝ
+- Seattle, Washington, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- San Jose, California, USA ๐Ÿ‡บ๐Ÿ‡ธ
+- Toronto, Canada ๐Ÿ‡จ๐Ÿ‡ฆ
+
+__South America__
+
+- Bogota, Colombia ๐Ÿ‡จ๐Ÿ‡ด
+- Buenos Aires, Argentina ๐Ÿ‡ฆ๐Ÿ‡ท
+- Rio de Janeiro, Brazil ๐Ÿ‡ง๐Ÿ‡ท
+- Sao Paulo, Brazil ๐Ÿ‡ง๐Ÿ‡ท (free)
+- Santiago, Chile ๐Ÿ‡จ๐Ÿ‡ฑ
+
+__Oceania__
+
+- Sydney, Australia ๐Ÿ‡ฆ๐Ÿ‡บ (free)
+
+### Frequency
+
+The check interval, we support the following frequencies:
+- 30 seconds
+- 1 minute
+- 5 minutes
+- 10 minutes
+- 30 minutes
+- 1 hour
+
+### Response Time Thresholds
+#### Timeout
+The timeout for the HTTP request, default: `45 seconds`
+#### Degraded
+The duration for which the HTTP request is considered degraded.
+
+### Retry
+The number of retries for the HTTP request. Default: `3`
+
+### OpenTelemetry
+#### OTPL Endpoint
+The endpoint we use to export the metrics. We only support HTTP endpoint.
+#### OTLP Headers
+The headers we use to export the metrics to your otlp endpoint.
diff --git a/apps/docs/src/content/docs/reference/terraform.mdx b/apps/docs/src/content/docs/reference/terraform.mdx
new file mode 100644
index 000000000..658f60601
--- /dev/null
+++ b/apps/docs/src/content/docs/reference/terraform.mdx
@@ -0,0 +1,27 @@
+---
+title: Terraform Provider
+description:
+ "Use OpenStatus Terraform provider to manage your monitors and status page."
+---
+
+Here you can find the official OpenStatus Terraform provider. This provider
+allows you to manage your monitors and status page using Terraform.
+
+https://registry.terraform.io/providers/openstatusHQ/openstatus/latest
+
+## Usage
+
+```
+provider "openstatus" {
+ openstatus_api_token= "YOUR_API_TOKEN"
+}
+
+resource "openstatus_monitor" "my_monitor" {
+ url = "https://www.openstatus.dev"
+ regions= ["iad", "jnb"]
+ periodicity = "10m"
+ name = "test-monitor"
+ active = true
+ description = "This is a test monitor"
+}
+```
diff --git a/apps/docs/src/content/docs/status-page/create-status-page.mdx b/apps/docs/src/content/docs/status-page/create-status-page.mdx
index be8998519..f391f5758 100644
--- a/apps/docs/src/content/docs/status-page/create-status-page.mdx
+++ b/apps/docs/src/content/docs/status-page/create-status-page.mdx
@@ -1,24 +1,4 @@
---
-title: How to create a status page?
-description: "How to create a status page in OpenStatus"
+title: About this project
+description: Learn more about the project Iโ€™m working on.
---
-
-import { Image } from 'astro:assets';
-
-import StatusPageEmpty from '../../../assets/status-page/status-page-empty.png';
-
-When you create your first status page, you will see an empty page.
-
-In order to create your status page, you need to create at least one monitor.
-
-<Image
- src={StatusPageEmpty}
- alt="Create your status page"
-/>
-
-
-Then you need to give your status page a name and choose a slug.
-
-Your status page will be available at `https://<slug>.openstatus.dev/`.
-
-You can also set a [custom domain](/status-page/advanced/custom-domain) for your status page.
\ No newline at end of file
diff --git a/apps/docs/src/content/docs/tutorial/get-started-with-openstatus-cli.mdx b/apps/docs/src/content/docs/tutorial/get-started-with-openstatus-cli.mdx
new file mode 100644
index 000000000..61cf557d3
--- /dev/null
+++ b/apps/docs/src/content/docs/tutorial/get-started-with-openstatus-cli.mdx
@@ -0,0 +1,61 @@
+---
+title: Get Started with openstatus CLI
+---
+
+import { Image } from 'astro:assets';
+import CLI from '../../../assets/tutorial/get-started-with-openstatus-cli/CLI.png';
+
+<Image
+ src={CLI}
+ alt="openstatus CLI"
+/>
+
+## Installation
+
+
+Install the OpenStatus CLI to set up your monitors straight in your code.
+
+### OS X
+```bash
+brew install openstatusHQ/cli/openstatus --cask
+```
+or
+
+```bash
+curl -sSL instl.sh/openstatushq/cli/macos | bash
+```
+
+### Linux
+```bash
+curl -sSL instl.sh/openstatushq/cli/linux | bash
+```
+
+### Windows
+
+```bash
+iwr instl.sh/openstatushq/cli/windows | iex
+```
+
+## Add API Key
+
+Create an API key in your workspace settings.
+
+```bash
+export OPENSTATUS_API_TOKEN=<your-api-token>
+```
+
+## Import Monitors
+
+Import monitors from your workspace to a YAML file.
+
+```bash
+openstatus monitors import
+```
+
+### Manage Monitors
+
+Add, remove, or update monitors from a YAML file and apply your changes.
+
+```bash
+openstatus monitors apply
+```
diff --git a/apps/docs/src/content/docs/tutorial/getting-started.mdx b/apps/docs/src/content/docs/tutorial/getting-started.mdx
new file mode 100644
index 000000000..a615c8b02
--- /dev/null
+++ b/apps/docs/src/content/docs/tutorial/getting-started.mdx
@@ -0,0 +1,9 @@
+---
+title: Getting Started
+---
+
+Here are some tutorials to help you get started with OpenStatus:
+
+- [How to create your first monitor with OpenStatus](/tutorial/how-to-create-monitor)
+- [How to create a status page?](/tutorial/how-to-create-status-page)
+- [Get Started with openstatus CLI](/tutorial/get-started-with-openstatus-cli)
diff --git a/apps/docs/src/content/docs/monitoring/create-monitor.mdx b/apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx
similarity index 77%
rename from apps/docs/src/content/docs/monitoring/create-monitor.mdx
rename to apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx
index 83d70ec9d..7b19487cd 100644
--- a/apps/docs/src/content/docs/monitoring/create-monitor.mdx
+++ b/apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx
@@ -1,19 +1,19 @@
---
-title: Creating Your First Monitor
+title: Create Your First Monitor
description: "How to create your first monitor with OpenStatus"
---
import { Image } from 'astro:assets';
import { Aside, CardGrid, LinkCard } from '@astrojs/starlight/components';
-import monitorOverview from '../../../assets/monitor/create-monitor/monitor-overview.png';
-import createMonitor from '../../../assets/monitor/create-monitor/create-monitor-1.png';
-import createMonitor2 from '../../../assets/monitor/create-monitor/create-monitor-2.png';
+import monitorOverview from '../../../assets/tutorial/create-monitor/monitor-overview.png';
+import createMonitor from '../../../assets/tutorial/create-monitor/create-monitor-1.png';
+import createMonitor2 from '../../../assets/tutorial/create-monitor/create-monitor-2.png';
import { ShowcaseYouTube } from 'starlight-showcases'
-This guide 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.
+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.
## Get Started in 1 Minute
@@ -89,30 +89,6 @@ You can add any number of custom HTTP headers to your request. This is particula
-## Fine-Tuning Your Monitor โš™๏ธ
-
-Once you've configured the basics, you can further refine your monitor's behavior with these advanced options:
-
-<CardGrid>
- <LinkCard
- title="Assertions"
- href="/monitoring/customization/assertions"
- />
- <LinkCard
- title="Frequency"
- href="/monitoring/customization/frequency"
- />
- <LinkCard
- title="Locations"
- href="/monitoring/customization/locations"
- />
- <LinkCard
- title="Timing"
- href="/monitoring/customization/timing"
- />
-</CardGrid>
-
-
## Important Considerations
### Monitoring Third-Party Endpoints
diff --git a/apps/docs/src/content/docs/tutorial/how-to-create-status-page.mdx b/apps/docs/src/content/docs/tutorial/how-to-create-status-page.mdx
new file mode 100644
index 000000000..b4521db47
--- /dev/null
+++ b/apps/docs/src/content/docs/tutorial/how-to-create-status-page.mdx
@@ -0,0 +1,50 @@
+---
+title: How to create a status page?
+description: "How to create a status page in OpenStatus"
+---
+
+import { Image } from 'astro:assets';
+
+import CreateStatusPage1 from '../../../assets/tutorial/create-status-page/create-status-page-1.png';
+
+import CreateStatusPage2 from '../../../assets/tutorial/create-status-page/create-status-page-2.png';
+
+
+
+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.
+
+## Get started
+
+### 1. Create the status page
+
+Navigate to the **Status Pages** page from the sidebar and click the **Create Status Page** button. This will open a new configuration screen.
+
+<Image
+ src={CreateStatusPage1}
+ alt="Create your status page"
+/>
+
+
+### 2. Configure the status page
+
+After creating the status page, you can configure it
+
+
+
+<Image
+ src={CreateStatusPage2}
+ alt="Configure your status page"
+/>
+
+#### Monitors
+
+You need to add monitors to your status page. Monitors are used to check the status of your services.
+
+#### Custom domain
+
+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.
+
+
+#### Password Protection
+
+You can add password protection to your status page. Password protection allows you to restrict access to your status page to only authorized users.
diff --git a/apps/docs/src/content/docs/tutorials.mdx b/apps/docs/src/content/docs/tutorials.mdx
new file mode 100644
index 000000000..998dfd39c
--- /dev/null
+++ b/apps/docs/src/content/docs/tutorials.mdx
@@ -0,0 +1,4 @@
+---
+title: Tutorials
+description: Learn more about the project Iโ€™m working on.
+---