Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
Improve documentation with Diátaxis framework (#1702)
Copilot411711c84c3d
diff --git a/GEMINI.md b/GEMINI.mdnew file mode 100644index 000000000..8a59ed66c--- /dev/null+++ b/GEMINI.md@@ -0,0 +1,91 @@+# GEMINI.md++This file provides a comprehensive overview of the OpenStatus project, its architecture, and development conventions to be used as instructional context for future interactions.++## Project Overview++OpenStatus is an open-source synthetic monitoring platform. It allows users to monitor their websites and APIs from multiple locations and receive notifications when they are down or slow.++The project is a monorepo managed with pnpm workspaces and Turborepo. It consists of several applications and packages that work together to provide a complete monitoring solution.++### Core Technologies++- **Frontend:**+ - Next.js (with Turbopack)+ - React+ - Tailwind CSS+ - shadcn/ui+ - tRPC+- **Backend:**+ - Hono (Node.js framework)+ - Go+- **Database:**+ - Turso (libSQL)+ - Drizzle ORM+- **Data Analytics:**+ - Tinybird+- **Authentication:**+ - NextAuth.js+- **Build System:**+ - Turborepo++### Architecture++The OpenStatus platform is composed of three main applications:++- **`apps/dashboard`**: A Next.js application that provides the main user interface for managing monitors, viewing status pages, and configuring notifications.+- **`apps/server`**: A Hono-based backend server that provides the API for the dashboard application.+- **`apps/checker`**: A Go application responsible for performing the actual monitoring checks from different locations.++These applications are supported by a collection of shared packages in the `packages/` directory, which provide common functionality such as database access, UI components, and utility functions.++## Building and Running++The project can be run using Docker (recommended) or a manual setup.++### With Docker++1. Copy the example environment file:+ ```sh+ cp .env.docker.example .env.docker+ ```+2. Start all services:+ ```sh+ docker compose up -d+ ```+3. Access the applications:+ - Dashboard: `http://localhost:3002`+ - Status Pages: `http://localhost:3003`++### Manual Setup++1. Install dependencies:+ ```sh+ pnpm install+ ```+2. Initialize the development environment:+ ```sh+ pnpm dx+ ```+3. Run a specific application:+ ```sh+ pnpm dev:dashboard+ pnpm dev:status-page+ pnpm dev:web+ ```++### Running Tests++To run the test suite, use the following command:++```sh+pnpm test+```++## Development Conventions++- **Monorepo:** The project is organized as a monorepo using pnpm workspaces. All applications and packages are located in the `apps/` and `packages/` directories, respectively.+- **Build System:** Turborepo is used to manage the build process. The `turbo.json` file defines the build pipeline and dependencies between tasks.+- **Linting and Formatting:** The project uses Biome for linting and formatting. The configuration can be found in the `biome.jsonc` file.+- **Code Generation:** The project uses `drizzle-kit` for database schema migrations.+- **API:** The backend API is built using Hono and tRPC. The API is documented using OpenAPI.diff --git a/apps/docs/src/content/docs/alerting/overview.mdx b/apps/docs/src/content/docs/alerting/overview.mdxdeleted file mode 100644index 3ee0096eb..000000000--- a/apps/docs/src/content/docs/alerting/overview.mdx+++ /dev/null@@ -1,35 +0,0 @@-----title: Overview-description: "Discover the different notification channels available in OpenStatus"-----import { Card } from '@astrojs/starlight/components';-import { CardGrid } from '@astrojs/starlight/components';-import { Image } from 'astro:assets';-import { LinkCard } from '@astrojs/starlight/components';-import DiscordNotification from '../../../assets/notification/discord-notification.png';--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.--By default we don't send any notification. You need to connect your monitor to a notification channel to receive alerts.-- <Image- src={DiscordNotification}- alt="Create your notification bot"- />--## Notification channels--<CardGrid>- <LinkCard title="Email ✉️" href="/alerting/providers/email" description=" Receive an email"/>- <LinkCard title="Slack 📣" href="/alerting/providers/slack" description="Get notified on Slack" />- <LinkCard title="Discord 🤖" href="/alerting/providers/discord" description="Get notified on Discord" />- <LinkCard title="SMS 📱" href="/alerting/providers/sms" description="Receive a text message" />- <LinkCard title="ntfy.sh 🔔" href="/alerting/providers/ntfy" description="Receive a ntfy.sh notification" />- <LinkCard title="Pagerduty 📟" href="/alerting/providers/pagerduty" description="Receive a pagerduty notification"/ >- <LinkCard title="Phone 📞" href="/alerting/providers/phone-call" description="Get called on your phone" />- <LinkCard title="Telegram 📡" href="/alerting/providers/telegram" description="Get notified on Telegram" />- <LinkCard title="Webhook 🌐" href="/alerting/providers/webhook" description="Get notified by webhook" />--</CardGrid>diff --git a/apps/docs/src/content/docs/alerting/providers/discord.mdx b/apps/docs/src/content/docs/alerting/providers/discord.mdxdeleted file mode 100644index 5cc6c0c6d..000000000--- a/apps/docs/src/content/docs/alerting/providers/discord.mdx+++ /dev/null@@ -1,13 +0,0 @@-----title: Discord-description: "How to set up Discord notifications in OpenStatus to get alerts when your synthetic check fail"------When a monitor is down you can set up a webhook to send a message to a Discord-channel. You can set up a webhook in the Discord settings. The webhook URL-should look something like this:-`https://discordapp.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz1234567890`--## How to set up your Discord webhook--https://support.discord.com/hc/en-us/articles/228383668diff --git a/apps/docs/src/content/docs/alerting/providers/email.mdx b/apps/docs/src/content/docs/alerting/providers/email.mdxdeleted file mode 100644index 62734712a..000000000--- a/apps/docs/src/content/docs/alerting/providers/email.mdx+++ /dev/null@@ -1,7 +0,0 @@-----title: Email-description: "How to set up Email notifications in OpenStatus to get alerts when your synthetic check fail"-------When we create an incident we send an email to the email provided.diff --git a/apps/docs/src/content/docs/alerting/providers/ntfy.mdx b/apps/docs/src/content/docs/alerting/providers/ntfy.mdxdeleted file mode 100644index 4e1475666..000000000--- a/apps/docs/src/content/docs/alerting/providers/ntfy.mdx+++ /dev/null@@ -1,12 +0,0 @@-----title: ntfy.sh-description: "How to set up ntfy.sh notifications in OpenStatus to get alerts when your synthetic check fail"------[ntfy.sh](https://ntfy.sh/) is an open-source servicer that allows you to receive push notifications on your phone.----Go to the Notifications Page . Select `ntfy.sh` from the list of available integrations.--Enter your ntfy topic (required), your custom server URL, and your bearer token.diff --git a/apps/docs/src/content/docs/alerting/providers/opsgenie.mdx b/apps/docs/src/content/docs/alerting/providers/opsgenie.mdxdeleted file mode 100644index e29673889..000000000--- a/apps/docs/src/content/docs/alerting/providers/opsgenie.mdx+++ /dev/null@@ -1,69 +0,0 @@-----title: OpsGenie-description: "How to set up OpsGenie notifications in OpenStatus to get alerts when your synthetic check fail"------import { Image} from 'astro:assets';-import OpsGenie1 from '../../../../assets/notification/opsgenie/opsgenie-1.png';-import OpsGenie2 from '../../../../assets/notification/opsgenie/opsgenie-2.png';-import OpsGenie3 from '../../../../assets/notification/opsgenie/opsgenie-3.png';-import OpsGenie4 from '../../../../assets/notification/opsgenie/opsgenie-4.png';-import OpsGenie5 from '../../../../assets/notification/opsgenie/opsgenie-5.png';--Get Notified on OpsGenie when we create an incident.--## How to connect OpsGenie--### Create an OpsGenie Integration--First we need to create an integration in OpsGenie.--Go to your team in OpsGenie and select `Integrations` from the menu.--- <Image- src={OpsGenie1}- alt="OpsGenie integration page"- />-In the integrations page, search for `API` and select it.--- <Image- src={OpsGenie2}- alt="Connect to OpsGenie"- />--Give your integration a name and save it.-Copy your API key and save it. You will need it to connect OpenStatus to OpsGenie.-- <Image- src={OpsGenie3}- alt="Connect to OpsGenie"- />---### Connect your OpenStatus account to OpsGenie---Go to the Alerts Page . Select `OpsGenie` from the list of available integrations.--- <Image- src={OpsGenie4}- alt="OpenStatus Notifications Page"- />---Give you integration a name and paste the API key you copied from OpsGenie and select the region of your OpsGenie account.-- <Image- src={OpsGenie5}- alt="Connect to OpsGenie in OpenStatus"- />--Select the service you want to use to send notifications. You can create a new service if you don't have one.---You are now connected to OpsGenie.--You will receive some notifications if we detect an incidentdiff --git a/apps/docs/src/content/docs/alerting/providers/pagerduty.mdx b/apps/docs/src/content/docs/alerting/providers/pagerduty.mdxdeleted file mode 100644index 258d6ee29..000000000--- a/apps/docs/src/content/docs/alerting/providers/pagerduty.mdx+++ /dev/null@@ -1,41 +0,0 @@-----title: PagerDuty-description: "How to set up PagerDuty notifications in OpenStatus to get alerts when your synthetic check fail"------import { Image} from 'astro:assets';-import PagerDuty1 from '../../../../assets/notification/pagerduty/pagerduty-1.png';-import PagerDuty2 from '../../../../assets/notification/pagerduty/pagerduty-2.png';-import PagerDuty3 from '../../../../assets/notification/pagerduty/pagerduty-3.png';--Get Notified on PagerDuty when we create an incident.--## How to connect PagerDuty--Go to the Notifications Page . Select `PagerDuty` from the list of available integrations.---- <Image- src={PagerDuty1}- alt="Connect to PagerDuty"- />--You will be redirected to the PagerDuty website to authorize OpenStatus to send notifications to your account.-- <Image- src={PagerDuty3}- alt="Connect to PagerDuty"- />---Select the service you want to use to send notifications. You can create a new service if you don't have one.-- <Image- src={PagerDuty2}- alt="Connect to PagerDuty"- />--You are now connected to PagerDuty. Give your integration a name and save it.--You will receive some notifications if we detect an incidentdiff --git a/apps/docs/src/content/docs/alerting/providers/phone-call.mdx b/apps/docs/src/content/docs/alerting/providers/phone-call.mdxdeleted file mode 100644index 4b6936f59..000000000--- a/apps/docs/src/content/docs/alerting/providers/phone-call.mdx+++ /dev/null@@ -1,9 +0,0 @@-----title: Phone call-description: "How to set up phone call notifications in OpenStatus to get alerts when your synthetic check fail"-------Receive a phone call when your monitor is down.--🚧 Coming soon 🚧diff --git a/apps/docs/src/content/docs/alerting/providers/slack.mdx b/apps/docs/src/content/docs/alerting/providers/slack.mdxdeleted file mode 100644index e1cb206a3..000000000--- a/apps/docs/src/content/docs/alerting/providers/slack.mdx+++ /dev/null@@ -1,9 +0,0 @@-----title: Slack-description: "How to set up Slack notifications in OpenStatus to get alerts when your synthetic check fail"-------When a monitor is down, a message can be sent to a Slack channel. To enable this-feature, you need to create a Slack webhook. You can do this by following the-instructions [here](https://api.slack.com/incoming-webhooks).diff --git a/apps/docs/src/content/docs/alerting/providers/sms.mdx b/apps/docs/src/content/docs/alerting/providers/sms.mdxdeleted file mode 100644index 50a91fded..000000000--- a/apps/docs/src/content/docs/alerting/providers/sms.mdx+++ /dev/null@@ -1,8 +0,0 @@-----title: SMS-description: "How to set up SMS notifications in OpenStatus to get alerts when your synthetic check fail"-------When you subscribe to a paid plan you can receive SMS notifications when your-monitor is down.diff --git a/apps/docs/src/content/docs/alerting/providers/telegram.mdx b/apps/docs/src/content/docs/alerting/providers/telegram.mdxdeleted file mode 100644index 382598648..000000000--- a/apps/docs/src/content/docs/alerting/providers/telegram.mdx+++ /dev/null@@ -1,7 +0,0 @@-----title: Telegram-description: "How to set up Telegram notifications in OpenStatus to get alerts when your synthetic check fail"-------🚧 Coming soon 🚧diff --git a/apps/docs/src/content/docs/alerting/providers/webhook.mdx b/apps/docs/src/content/docs/alerting/providers/webhook.mdxdeleted file mode 100644index 95e0640e3..000000000--- a/apps/docs/src/content/docs/alerting/providers/webhook.mdx+++ /dev/null@@ -1,101 +0,0 @@-----title: Webhook-description: "How to set up Webhook notifications in OpenStatus to get alerts when your synthetic check fail"-----## Setting Up Webhook Notifications-To set up Webhook notifications, follow these steps:--1. **Access the Notifications Tab**\-Navigate to your notifications tab within the application.--2. **Add a New Notification**\-Click on the "Add Notification" button and select Webhook as the notification type.--3. **Provide Notification URL**\-Enter the URL where OpenStatus will send the notification payload. This URL should be publicly accessible and capable of handling incoming POST requests.--4. **Optional: Add Custom Headers**\-If needed, you can include custom headers in your request for additional context or authentication.---## Notification Payloads---OpenStatus sends different payloads depending on the status of the monitor. Below are the payload structures for both-recovery and failure notifications.---### Payload for Monitor Recovery-When the monitor recovers, you will receive a notification with the following payload:-```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--In the event of a monitor failure, the notification will include the following payload:-```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(),-});-````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.mdxindex a66bcec72..341f7a380 100644--- a/apps/docs/src/content/docs/concept/best-practices-status-page.mdx+++ b/apps/docs/src/content/docs/concept/best-practices-status-page.mdx@@ -1,5 +1,6 @@---title: Best Practices for Status Pages+description: "How to communicate effectively during incidents and build user trust through transparency"---@@ -22,7 +23,17 @@ title: Best Practices for Status Pages+------------------------------------------------+```-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.+## Why status pages matter++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.++When done right, status pages:+- **Reduce support burden**: Users self-serve incident information+- **Build trust**: Transparency demonstrates accountability+- **Improve communication**: Centralized, consistent incident updates+- **Demonstrate professionalism**: Shows you take reliability seriously++Following a set of best practices ensures your status page is effective and helpful.@@ -67,7 +78,7 @@ When an incident occurs, provide a detailed and structured narrative.- **Resolved:** "The issue has been resolved, and all services are now operational."-### Make it Easily Accessible+### Make it easily accessibleYour status page should be easy to find.@@ -75,5 +86,48 @@ Your status page should be easy to find.- **Custom Domain:** Use a simple, memorable URL like status.yourcompany.com.+## Advanced considerations++### Scheduled maintenance++Communicate planned downtime in advance:+- Announce maintenance at least 72 hours ahead+- Show maintenance windows on the status page+- Send reminders 24 hours before maintenance++### Historical data++Show your track record:+- Display uptime percentages (30/60/90 days)+- Link to past incidents and post-mortems+- Be honest about past issues-it builds trust++### Subscriber notifications++Let users opt in to updates:+- Email notifications for incidents+- SMS for critical alerts (if available)+- RSS/Atom feeds for automated monitoring++## Common mistakes to avoid++1. **Over-promising uptime**: Don't claim 100% uptime if you haven't achieved it+2. **Hiding incidents**: Transparency beats saving face+3. **Technical jargon**: Write for non-technical audiences+4. **Infrequent updates**: During incidents, update every 30-60 minutes+5. **Separate status page hosting**: Your status page should work even when your service is down++## Implementing with openstatus++openstatus makes following these best practices easy:++- **[Create a status page](/tutorial/how-to-create-status-page)** - Quick setup+- **[Configure your page](/tutorial/how-to-configure-status-page)** - Customize appearance+- **[Set up notifications](/monitoring/customization/notification)** - Alert your team+- **[Understand uptime calculations](/concept/uptime-calculation-and-values)** - Transparent metrics++## Next steps-Following these practices turns your status page from a passive communication tool into an active driver of customer trust and confidence.+- **[Create your status page](/tutorial/how-to-create-status-page)** - Put these practices into action+- **[Understanding uptime monitoring](/concept/uptime-monitoring)** - Monitor what you communicate+- **[Status page reference](/reference/status-page)** - Technical configuration optionsdiff --git a/apps/docs/src/content/docs/concept/getting-started.mdx b/apps/docs/src/content/docs/concept/getting-started.mdxindex 595a8b24f..3ce8834c2 100644--- a/apps/docs/src/content/docs/concept/getting-started.mdx+++ b/apps/docs/src/content/docs/concept/getting-started.mdx@@ -1,11 +1,35 @@----title: Getting Started+title: Understanding openstatus+description: Deep dive into the concepts, architecture, and design decisions behind openstatus+sidebar:+ label: Getting Started+ order: 1---+## 💡 Concepts-Here’s some content to help you get started with the concept behind OpenStatus.+### What you'll find here-- [Uptime Monitoring](/concept/uptime-monitoring)-- [Best Practices for Status Pages](/concept/best-practices-status-page)-- [Uptime Monitoring as Code](/concept/uptime-monitoring-as-code)-- [Latency vs Response Time](/concept/latency-vs-response-time)+Our docs help you:+- Understand core monitoring concepts+- Learn best practices and design patterns+- Make informed decisions about your monitoring strategy+- Appreciate the reasoning behind openstatus features++### Core Concepts++Build a solid foundation:++- **[Uptime Monitoring](/concept/uptime-monitoring)** - What uptime monitoring is, why it matters, and how it works+- **[Uptime Calculation and Values](/concept/uptime-calculation-and-values)** - How uptime percentages are calculated and what they really mean+- **[Latency vs Response Time](/concept/latency-vs-response-time)** - Understanding the difference between these crucial metrics++### Best Practices++Learn from experience:++- **[Best Practices for Status Pages](/concept/best-practices-status-page)** - How to communicate effectively during incidents and maintain user trust+- **[Uptime Monitoring as Code](/concept/uptime-monitoring-as-code)** - Why and how to manage monitoring configuration as code+++Have questions or want to discuss these concepts? [Join our community](/help/support/) and share your thoughts!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.mdxindex 1e50f67d2..968d62877 100644--- a/apps/docs/src/content/docs/concept/latency-vs-response-time.mdx+++ b/apps/docs/src/content/docs/concept/latency-vs-response-time.mdx@@ -1,10 +1,21 @@----title: Latency vs Response Time for a request+title: Understanding Latency vs Response Time+description: "Deep dive into the difference between latency and response time, and why both matter for monitoring"----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.+## The confusion++Latency and response time are often used interchangeably, but they measure different things. Understanding the distinction is crucial for effective monitoring and performance optimization.++**The key difference:**+- **Latency** measures network travel time+- **Response time** measures total time including server processing++Both metrics matter, but for different reasons.++## What is latency?-## What is Latency?+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.```openstatus Network Server (Website)@@ -58,7 +69,7 @@ The server processing time is the duration the server spends on tasks like: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+## Why the distinction matters for uptime monitoringUnderstanding the difference between these two metrics is crucial for diagnosing performance issues.@@ -69,3 +80,47 @@ Understanding the difference between these two metrics is crucial for diagnosing- **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.++## Practical implications++### For monitoring strategy++- **Monitor both metrics**: Don't rely on just one+- **Set appropriate thresholds**: Latency thresholds should be lower than response time thresholds+- **Consider geographic factors**: Latency varies by monitoring location+- **Track trends**: Sudden changes in either metric indicate issues++### For optimization++- **Reduce latency**: Use CDNs, optimize routing, choose closer hosting+- **Improve response time**: Optimize code, database queries, caching+- **User location matters**: Users far from your server will always see higher latency++### Common scenarios++**Scenario 1: Consistent latency, variable response time**+- Indicates server-side performance issues+- Look at: Database queries, API calls, resource utilization++**Scenario 2: High latency from specific regions**+- Indicates geographic network issues+- Solution: Add regional monitoring points or CDN++**Scenario 3: Both metrics degrading**+- Could be network saturation or DDoS attack+- Check: Network bandwidth, traffic patterns, security++## What openstatus tracks++openstatus monitors and displays:+- **Total response time**: The complete user experience+- **Detailed timing breakdown**: DNS, TCP, TLS, request, response+- **Regional differences**: Compare performance across locations+- **Historical trends**: Identify patterns over time++## Next steps++- **[Create your first monitor](/tutorial/how-to-create-monitor)** - Start tracking these metrics+- **[Understanding uptime monitoring](/concept/uptime-monitoring)** - Broader monitoring concepts+- **[Monitor data collected](/monitoring/monitor-data-collected)** - All metrics we track+- **[HTTP monitor reference](/reference/http-monitor)** - Technical specificationsdiff --git a/apps/docs/src/content/docs/concept/uptime-calculation-and-values.mdx b/apps/docs/src/content/docs/concept/uptime-calculation-and-values.mdxindex 8b1d2bb5a..928134a27 100644--- a/apps/docs/src/content/docs/concept/uptime-calculation-and-values.mdx+++ b/apps/docs/src/content/docs/concept/uptime-calculation-and-values.mdx@@ -65,7 +65,7 @@ Like with duration, hover cards display incidents and status reports, giving you## Manual TypeThe manual type is for teams who want to **fully control what’s shown** on your status page, without relying on automatic checks.-By default, your monitor is marked operational. You can then manually create status reports whenever you want to reflect changes — independent of any monitoring data.+By default, your monitor is marked operational. You can then manually create status reports whenever you want to reflect changes - independent of any monitoring data.This is ideal if:- you don’t have synthetic monitoring set up yet,@@ -75,4 +75,4 @@ In this mode, all displayed uptime values and statuses come from your shared repIn simple terms: `uptime = (total duration - status report duration) / total duration`-> **Note**: the values you are defining are attached to a status page. You cannot change them per monitor (for now).\ No newline at end of file+> **Note**: the values you are defining are attached to a status page. You cannot change them per monitor (for now).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.mdxindex 42c12e404..1a4af920f 100644--- a/apps/docs/src/content/docs/concept/uptime-monitoring-as-code.mdx+++ b/apps/docs/src/content/docs/concept/uptime-monitoring-as-code.mdx@@ -1,7 +1,26 @@----title: Uptime Monitoring as Code+title: Understanding Monitoring as Code+description: "Why and how to manage monitoring configuration as code for GitOps workflows"---import { Code } from '@astrojs/starlight/components';++## The traditional approach (and its problems)++Traditionally, monitoring is configured through web dashboards:+1. Log into a web interface+2. Click through forms to create monitors+3. Manually replicate configuration across environments+4. No audit trail of who changed what+5. Difficult to review changes before they go live++This works for small teams with few monitors, but doesn't scale.++## What is monitoring as code?++**Monitoring as Code** treats your monitoring configuration the same way you treat your application code: as text files that can be versioned, reviewed, and deployed through automated pipelines.++Instead of clicking buttons, you define monitors in YAML:+export const code = `# yaml-language-server: $schema=https://www.openstatus.dev/schema.jsonuptime-monitor:@@ -21,7 +40,7 @@ uptime-monitor:url: https://openstat.usmethod: GETheaders:- User-Agent: OpenStatus+ User-Agent: openstatusassertions:- kind: statusCodecompare: eq@@ -44,7 +63,7 @@ graphql-monitor:url: https://api.github.com/graphqlmethod: POSTheaders:- User-Agent: OpenStatus+ User-Agent: openstatusAuthorization: Bearer YOUR_TOKEN_HEREbody: |{@@ -52,7 +71,7 @@ graphql-monitor:}`-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.+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?@@ -80,7 +99,7 @@ Here’s an example of what your `openstatus.yaml` file might look like:### 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.+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:**@@ -88,3 +107,20 @@ Once your `openstatus.yaml` file is ready, you use our [command-line interface (- `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.++## Best practices++1. **Start simple**: Begin with a few monitors, expand as you learn+2. **Use templates**: Create reusable patterns for common monitor types+3. **Environment variables**: Use secrets management for tokens and sensitive data+4. **Review changes**: Always review diffs before applying+5. **Document decisions**: Use commit messages to explain "why"++## Next steps++Ready to implement monitoring as code?++- **[Get Started with CLI](/tutorial/get-started-with-openstatus-cli)** - Install and configure the CLI+- **[Monitor Your MCP Server](/guides/how-to-monitor-mcp-server/)** - Real-world example+- **[CLI Reference](/reference/cli-reference)** - Complete command documentation+- **[YAML Examples](https://github.com/openstatusHQ/cli-template)** - Sample configurationsdiff --git a/apps/docs/src/content/docs/concept/uptime-monitoring.mdx b/apps/docs/src/content/docs/concept/uptime-monitoring.mdxindex be6fc3aea..7ca59bef0 100644--- a/apps/docs/src/content/docs/concept/uptime-monitoring.mdx+++ b/apps/docs/src/content/docs/concept/uptime-monitoring.mdx@@ -1,8 +1,17 @@----title: About Uptime Monitoring+title: Understanding Uptime Monitoring+description: A deep dive into uptime monitoring concepts, architecture, and best practices---++## What is 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.+Uptime monitoring is fundamentally about answering three questions:+1. **Is my service available?** Can users reach it?+2. **Is it performing well?** Are response times acceptable?+3. **Is it functioning correctly?** Is it returning the expected data?+```+----------------+@@ -88,6 +97,43 @@ When planning your own uptime monitoring system, consider the following:- **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.+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.++## The human factor++While uptime monitoring is largely automated, it's important to remember the human aspects:++- **Alert fatigue**: Too many false positives can lead teams to ignore alerts. Fine-tune your monitoring to reduce noise.+- **On-call burden**: Distribute monitoring responsibilities fairly and ensure adequate coverage.+- **Communication**: During incidents, clear communication with users is as important as technical fixes.+- **Post-mortems**: Learn from downtime by conducting blameless post-mortems.++## Monitoring philosophy++Different approaches to monitoring reflect different philosophies:++- **Optimistic monitoring**: Assume everything is working unless proven otherwise. Alert on failures.+- **Pessimistic monitoring**: Assume nothing works unless actively verified. Alert on missing data.+- **SLI/SLO based**: Monitor Service Level Indicators against defined Service Level Objectives.++openstatus supports all these approaches, letting you choose what works best for your team.++## Beyond basic availability++Modern uptime monitoring goes beyond simple "up or down" checks:++- **Performance monitoring**: Track response times and identify degradation before outages.+- **Geographic monitoring**: Verify availability from multiple regions to catch regional issues.+- **Synthetic monitoring**: Simulate user journeys to catch functional issues.+- **Real user monitoring (RUM)**: Complement synthetic checks with actual user experience data.++## Next steps++Now that you understand uptime monitoring concepts:++- **[Get started with a monitor](/tutorial/how-to-create-monitor)** - Apply these concepts in practice+- **[Learn about uptime calculations](/concept/uptime-calculation-and-values)** - Understand how uptime percentages work+- **[Best practices for status pages](/concept/best-practices-status-page)** - Communicate effectively during incidents+- **[Monitoring as Code](/concept/uptime-monitoring-as-code)** - Manage monitoring configuration programmaticallydiff --git a/apps/docs/src/content/docs/contributing/getting-started.mdx b/apps/docs/src/content/docs/contributing/getting-started.mdxdeleted file mode 100644index 0a0f76e77..000000000--- a/apps/docs/src/content/docs/contributing/getting-started.mdx+++ /dev/null@@ -1,47 +0,0 @@-----title: Getting Started-------## Setup--1. Clone the repository--```sh-git clone https://github.com/openstatushq/openstatus.git-```--2. Install dependencies--```sh-pnpm install-```--3. Initialize the development environment--Launch the database in one terminal:--```sh-turso dev --db-file openstatus-dev.db-```--In another terminal, run the following command:--```sh-pnpm dx-```--4. Launch the web app--```sh-pnpm dev:web-```--It will:--- run the web app on port `3000`--5. See the results:--- open [http://localhost:3000](http://localhost:3000) for the web app-diff --git a/apps/docs/src/content/docs/contributing/requirements.mdx b/apps/docs/src/content/docs/contributing/requirements.mdxdeleted file mode 100644index d0a15656a..000000000--- a/apps/docs/src/content/docs/contributing/requirements.mdx+++ /dev/null@@ -1,80 +0,0 @@-----title: Requirements------import { Aside } from "@astrojs/starlight/components";--<Aside>WIP</Aside>--## System Requirements--Before you start, make sure you have the following applications and their-minimum versions installed, in addition to Node.js and pnpm (as mentioned-earlier):--- [Node.js 18.0.0](https://nodejs.org/) or later.-- [pnpm 8.6.2](https://pnpm.io/) or later.-- macOS, Windows (including WSL), and Linux are supported.--## Installing Node.js--To install Node.js, follow the instructions based on your operating system:--- For Windows or macOS, visit the official Node.js website:- [https://nodejs.org/](https://nodejs.org/) and download the latest or LTS- version (18.0.0 or above). Run the installer and follow the setup wizard.--- For Linux, you can use a package manager- ([nvm](https://github.com/nvm-sh/nvm.git/)) or download the binaries from the- official Node.js website. For example, using the package manager `apt` on- Ubuntu:-- ```bash- sudo apt update- sudo apt install nodejs- ```-- Ensure that the installed version is 18.0.0 or above:-- ```bash- node --version- ```--## Installing pnpm--To install pnpm, you can use npm, the Node.js package manager. Open your-terminal or command prompt and run the following command:--```bash-npm install -g pnpm-```--Make sure that the installed version of pnpm is 8.6.2 or above:--```bash-pnpm --version-```--Alternatively you can also install it from its official website-[https://pnpm.io/](https://pnpm.io/).--## **Optional Requirements for a Local Database:**--If you want to use a local database, it is recommended to install "brew" and-"sqld".--### Installing brew--To install brew, it is recommended to use brew.sh from-[https://brew.sh/](https://brew.sh/) and follow its instructions.---### Installing Turso--If you want to run Turso locally you can follow the instructions in the-[Turso CLI](https://docs.turso.tech/reference/turso-cli)---### Installing Bun--To install Bun, visit the official website [https://bun.sh/](https://bun.sh/)\ No newline at end of filediff --git a/apps/docs/src/content/docs/contributing/setup-env.mdx b/apps/docs/src/content/docs/contributing/setup-env.mdxdeleted file mode 100644index 62c647933..000000000--- a/apps/docs/src/content/docs/contributing/setup-env.mdx+++ /dev/null@@ -1,376 +0,0 @@-----title: Setup environment files------import { Aside } from "@astrojs/starlight/components";--import { Image } from 'astro:assets';--import Drizzle from '../../../assets/setup-env/drizzle-studio.png';--<Aside>WIP</Aside>--# Configuration of the .env file--The `.env` file contains various environment variables that need to be properly-configured for the application to work correctly. Below, I will explain how to-obtain the values for some of these variables.--## Setting up Resend for sending emails--The "RESEND for email" section in the `.env` file contains the "RESEND_API_KEY"-variable, which corresponds to the Resend API key that you need to set up to-send emails.--Here's how to obtain the Resend API key:--1. Access the Resend website at [https://resend.com](https://resend.com) and log- in with your account or create a new account if you don't have one.--2. Once you've logged in, look for the option to add a new API Key. You can do- this by clicking the corresponding button or navigating to the "API Keys"- section and creating it from there.--3. Fill in the necessary information to create the API Key, such as the name and- required permissions.--4. Once the API Key is created, copy its value, which usually starts with "re\_"- and includes a series of characters.--5. Paste this API Key value into the `.env` file under the "RESEND_API_KEY"- variable. It should look something like this (real values without- censorship):----```-# RESEND for email-RESEND_API_KEY=re_••••••••••••••••••••••••••••••••-```--Replace the key with the actual Resend API key you obtained from your Resend-account.--## Setting up Upstash (QStash and Redis)--The "Upstash for queue" section in the `.env` file contains the following-variables related to QStash and Redis:--```-# UPSTASH for queue-QSTASH_CURRENT_SIGNING_KEY=qstash-current-signing-key-QSTASH_NEXT_SIGNING_KEY=qstash-next-signing-key-QSTASH_TOKEN=qstash-token-QSTASH_URL=https://qstash.upstash.io/v1/publish/---# UPSTASH redis for waiting list-UPSTASH_REDIS_REST_URL=test-UPSTASH_REDIS_REST_TOKEN=test-```--To configure UPSTASH correctly, follow these steps:--### Obtaining QStash Keys--1. Log in to your UPSTASH account at- [https://upstash.com/](https://upstash.com/) or create a new account if you- don't have one yet.--2. Once logged in, go to- [https://console.upstash.com/qstash](https://console.upstash.com/qstash) and- copy the keys you need one by one. These keys are- "QSTASH_CURRENT_SIGNING_KEY", "QSTASH_NEXT_SIGNING_KEY", and "QSTASH_TOKEN".--3. Paste these keys into the `.env` file under their respective variables. It- should look something like this (real values without censorship):--```-# UPSTASH for queue-QSTASH_CURRENT_SIGNING_KEY=sig_•••••••••••••••••••••••••-QSTASH_NEXT_SIGNING_KEY=sig_•••••••••••••••••••••••••-QSTASH_TOKEN=ey••••••••••••••••••••••••••••••••-QSTASH_URL=https://qstash.upstash.io/v1/publish/-```--Replace the ellipsis with the actual keys you obtained from UPSTASH.--### Configuring Redis--> We have been using Redis for the waiting list in this project. It is not used-> currently. However, if you want to use it, you can follow the steps below to.--1. Create a Redis database in UPSTASH through- [https://console.upstash.com/](https://console.upstash.com/).--2. Once the database is created, access "Details" and go to the "API REST"- section, selecting the `.env` tab.--3. Copy the URL and token information displayed there and paste them in the- `.env` file under the following variables:--```-# UPSTASH redis for waiting list-UPSTASH_REDIS_REST_URL="https://•••••••••.upstash.io"-UPSTASH_REDIS_REST_TOKEN="•••••••••"-```--Replace the ellipsis with the actual URL and token of Redis you obtained from-UPSTASH.--## Setting up Tinybird--You will need to create an API token, Go to Auth tokens > Workspace tokens > Add-a new token > Select your token---```-# TinyBird-TINY_BIRD_API_KEY="•••••••••"-```--The [Tinybird CLI](https://www.tinybird.co/docs/cli.html) can be used to push-the pipes to the Tinybird server.--### Datasource--We ingest the monitor response into the `ping_response__v5` table. If you want-to have some dummy data to start with, check out the-[csv](https://raw.githubusercontent.com/openstatusHQ/openstatus/main/apps/docs/dummy/ping_response__v5.csv)-file.--> Warning: If importing the csv file, make sure to change the column names are-> identical (e.g. `monitorId` instead of `monitorid`). Otherwise, the pipes will-> not work.--### Pipes--The pipes we are using can be found under `@packages/tinybird/pipes`. Pipes are-used to transform data from one format to another. For example, we are using a-pipe to transform the data from the database `ping_response` into aggregated-data.--We currently have three pipes:--1. `status_timezone__v0`: returns aggregated data from the `ping_response`- table.-2. `response_list__v0`: returns the list of responses from the `ping_response`- table.-3. `home_stats__v0`: returns the total amount of pings during a timeframe from- the `ping_response` table.--## Setting up Turso (SQLite or Cloud Database)--The "TURSO SQLITE" section in the `.env` file allows you to configure Turso-database, either a local SQLite database or a cloud-based database.--### If you want to use a local database (optional):--To begin, install sqld with brew. If you don't have brew installed, we recommend-installing it from [brew.sh](https://brew.sh/) which works on macOS or Linux, or-WSL if you are using Windows.--```bash-brew tap libsql/sqld-brew install sqld-beta-```--Next, you can use the following command to start Turso with a SQLite database:--```bash-turso dev --db-file openstatus.db-```--By doing this, you'll be able to work with the local database without modifying-the `.env` file.--### If you want to use a cloud-based database with Turso--To use a cloud-based database with Turso, follow these steps:--1. Log in to your Turso account at [https://turso.tech/](https://turso.tech/) or- create a new account if you don't have one yet.--2. If this is your first time using Turso, it may prompt you to install the- client on your machine. Follow the steps provided on their website or refer- to their documentation- [https://docs.turso.tech/tutorials/get-started-turso-cli/step-01-installation](https://docs.turso.tech/tutorials/get-started-turso-cli/step-01-installation)- for client installation.--3. Once you have successfully installed the Turso client, open your terminal and- use the following command to authenticate:--```-turso auth login-```--4. Then, create a new database with the following command:--```-turso db create-```--Wait for a moment until the database is created, and you will be shown-information about the database, including a connection URL and an authentication-token.--5. Use the following commands to show the required information and create the- database in the `.env` file:--```-turso db show db-name-turso db tokens create db-name-```--Replace "db-name" with the name of your database. You should get the generated-URL and token, which should be placed in the `.env` file as follows (real values-without censorship):--```-# TURSO SQLITE-DATABASE_URL=libsql://my-database-example.turso.io-DATABASE_AUTH_TOKEN=ey••••••••••••••••••••••••••••••••-```--Remember to copy this information in both` app/web/.env` and `packages/db/.env`-and save the changes to the `.env` file once you have completed all the-configurations.--## **Connect datasource using tinybird-cli**--1. Log in to your tinybird account at https://www.tinybird.co/ or create a new- account if you don't have one yet.--2. Once logged in, go to your dashboard and copy the auth token and paste inside- `.env`-- > Please make sure you chose the admin token otherwise it may give an error- > like auth token invalid--3. Then download this file- [ping_response\_\_v5](https://raw.githubusercontent.com/openstatusHQ/openstatus/8d5c997aacd93becff2cf24ea1d08d33274d2c20/apps/docs/dummy/ping_response__v5.csv)--4. install the tinybird-cli--```-cd packages/tinybird-python3 -m venv .venv-source .venv/bin/activate-pip install tinybird-cli--```--5. Create a datasource from this file-- > Please make sure while importing you edit the table header fields in- > camelcase .--6. Create pipe from the datasource name as a `response_list__v1` and- `status_timezone__v0`--7. Inside `response_list__v0` pipe, create a endpoint by running a following- query :--```-%- SELECT id, latency, monitorId, pageId, region, statusCode, timestamp, url, workspaceId, cronTimestamp- FROM ping_response__v4- WHERE monitorId = {{ String(monitorId, 'openstatusPing') }}- {% if defined(region) %}- AND region = {{ String(region) }}- {% end %}- {% if defined(cronTimestamp) %}- AND cronTimestamp = {{ Int64(cronTimestamp) }}- {% end %}- {% if defined(fromDate) %}- AND cronTimestamp >= {{ Int64(fromDate) }}- {% end %}- {% if defined(toDate) %}- AND cronTimestamp <= {{ Int64(toDate) }}- {% end %}- ORDER BY timestamp DESC- LIMIT {{Int32(limit, 1000)}}-```--8. Inside `status_timezone__v0` pipe , create a endpoint by running a following- query :--```-VERSION 0--NODE group_by_cronTimestamp-SQL >-- %- SELECT- toDateTime(cronTimestamp / 1000, 'UTC') AS day,- -- only for debugging purposes- toTimezone(day, {{ String(timezone, 'Europe/Berlin') }}) as with_timezone,- toStartOfDay(with_timezone) as start_of_day,- avg(latency) AS avgLatency,- count() AS count,- count(multiIf((statusCode >= 200) AND (statusCode <= 299), 1, NULL)) AS ok- FROM ping_response__v4- WHERE- (day IS NOT NULL)- AND (day != 0)- AND monitorId = {{ String(monitorId, '1') }}- -- By default, we only only query the last 45 days- AND cronTimestamp >= toUnixTimestamp64Milli(- toDateTime64(toStartOfDay(date_sub(DAY, 45, now())), 3)- )- GROUP BY cronTimestamp, monitorId- ORDER BY day DESC----NODE group_by_day-SQL >-- %- SELECT- start_of_day as day,- sum(count) as count,- sum(ok) as ok,- round(avg(avgLatency)) as avgLatency- FROM group_by_cronTimestamp- GROUP BY start_of_day- ORDER BY start_of_day DESC- LIMIT {{ Int32(limit, 100) }}---```--### Setting up the database--We have an example database that you can use to get started. You can run it with-the following command:--```bash- turso dev --db-file openstatus-dev.db-```--It contains some dummy data that you can use to test the application.---- <Image- src={Drizzle}- alt="Drizzle"- />----```bash-cd packages/db-pnpm studio-```--## Conclusion--Once you have collected all the necessary information, you should save it in the-`.env` file to ensure proper configuration for your application. Following these-steps will enable your application to function effectively with the appropriate-settings for each service.--Open this url http://localhost:3000/app/love-openstatus to start using the app.diff --git a/apps/docs/src/content/docs/getting-started/introduction.mdx b/apps/docs/src/content/docs/getting-started/introduction.mdxindex b0fc20c8b..0c9d2eb15 100644--- a/apps/docs/src/content/docs/getting-started/introduction.mdx+++ b/apps/docs/src/content/docs/getting-started/introduction.mdx@@ -1,6 +1,6 @@---title: Getting Started with openstatus-description: "How to get started with OpenStatus?"+description: "How to get started with openstatus?"topic: docsnext: 'Start Monitoring'---@@ -8,7 +8,7 @@ next: 'Start Monitoring'import { Aside } from '@astrojs/starlight/components';-You can use OpenStatus by either signing up for our **cloud version** or by **self-hosting** the application on your own infrastructure.+You can use openstatus by either signing up for our **cloud version** or by **self-hosting** the application on your own infrastructure.## Cloud Version@@ -19,15 +19,38 @@ and begin monitoring your services in seconds.## Self-Hosted Version-For users who want to host OpenStatus on their own infrastructure, all our code is [open source](https://github.com/openstatushq/openstatus)+For users who want to host openstatus on their own infrastructure, all our code is [open source](https://github.com/openstatushq/openstatus).-While we are working on making the self-hosted version easier to deploy, you can start with a community-maintained option like the **Vercel Edge Checker**.+We offer a few ways to get started with self-hosting:-### Vercel Edge Checker+### With Docker (Recommended)-The Vercel Edge Checker is a lightweight version of OpenStatus that you can deploy to Vercel with a single click. It's a great way to get familiar with self-hosting OpenStatus.+The fastest way to get started for both development and self-hosting is with Docker.+```sh+# 1. Copy environment file+cp .env.docker.example .env.docker++# 2. Start all services+docker compose up -d++# 3. Access the application+open http://localhost:3002 # Dashboard+open http://localhost:3003 # Status Pages+```++For a complete guide on using Docker, including database setup and configuration, please see our [DOCKER.md](https://github.com/openstatushq/openstatus/blob/main/DOCKER.md) file.++### With Devbox++You can use [Devbox](https://www.jetify.com/devbox/) to easily manage your development environment.++1. Install Devbox+ ```sh+ curl -fsSL https://get.jetify.com/devbox | bash+ ```+2. Install project dependencies, build and start services+ ```sh+ devbox services up+ ```-<Aside>-We are actively working to simplify self-hosting and have an open [issue](https://github.com/openstatusHQ/openstatus/issues/322) on GitHub regarding this. Stay tuned!-</Aside>diff --git a/apps/docs/src/content/docs/guides/getting-started.mdx b/apps/docs/src/content/docs/guides/getting-started.mdxindex e5003b078..e62acb4c0 100644--- a/apps/docs/src/content/docs/guides/getting-started.mdx+++ b/apps/docs/src/content/docs/guides/getting-started.mdx@@ -1,17 +1,45 @@----title: Introduction-description: Guides to get started with OpenStatus guides+title: How-to Guides+description: Problem-solving guides for specific tasks with openstatussidebar:label: Introductionorder: 1----Here's some guides for the getting started with OpenStatus.+## 🛠️ How-to Guides+### What you'll find here-- [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)-- [How to deploy private location on Cloudflare Containers](/guides/how-to-deploy-probes-cloudflare-containers)+Our how-to guides are designed to help you:+- Solve specific problems with step-by-step instructions+- Implement advanced features and integrations+- Customize and extend your openstatus setup++### Monitoring & Integration++Extend your monitoring capabilities:++- **[Monitor Your MCP Server](/guides/how-to-monitor-mcp-server/)** - Set up monitoring for Model Context Protocol servers+- **[Export Metrics to OTLP Endpoint](/guides/how-to-export-metrics-to-otlp-endpoint)** - Send monitoring data to your observability platform+- **[Run Synthetic Tests in GitHub Actions](/guides/how-to-run-synthetic-test-github-action/)** - Automate testing in your CI/CD pipeline++### Status Pages & Widgets++Share your status with users:++- **[Add SVG Status Badge to GitHub README](/guides/how-to-add-svg-status-badge)** - Display real-time status in your repository+- **[Use React Status Widget](/guides/how-to-use-react-widget)** - Embed live status updates in your React application+- **[Deploy Status Page on Cloudflare Pages](/guides/how-deploy-status-page-cf-pages)** - Host your status page on Cloudflare's edge network++### Infrastructure & Deployment++Self-host and customize your setup:++- **[Deploy Private Locations on Cloudflare Containers](/guides/how-to-deploy-probes-cloudflare-containers)** - Run monitoring agents in your own infrastructure+- **[Self-Host openstatus](/guides/self-hosting-openstatus)** - Deploy openstatus on your own servers++### Related sections++- **[Tutorials](/tutorial/getting-started/)** - If you need step-by-step learning instead+- **[Explanations](/concept/getting-started/)** - To understand the concepts behind these guides+- **[Reference](/reference)** - For detailed technical specificationsdiff --git a/apps/docs/src/content/docs/guides/how-deploy-status-page-cf-pages.mdx b/apps/docs/src/content/docs/guides/how-deploy-status-page-cf-pages.mdxindex 0aa15d46f..ab55195ef 100644--- a/apps/docs/src/content/docs/guides/how-deploy-status-page-cf-pages.mdx+++ b/apps/docs/src/content/docs/guides/how-deploy-status-page-cf-pages.mdx@@ -1,6 +1,6 @@---title: How to deploy your own status page to Cloudflare Pages-description: Learn how to use OpenStatus monitoring data and deploy your own Status Page to cloudflare pages.+description: Learn how to use openstatus monitoring data and deploy your own Status Page to cloudflare pages.sidebar:label: Host your status page on Cloudflare Pages---@@ -9,11 +9,11 @@ import statusPage from '../../../assets/guides/how-deploy-status-page-cf-pages/s## Introduction-At OpenStatus, we believe that monitoring your endpoints should be easy and accessible to everyone.+At openstatus, we believe that monitoring your endpoints should be easy and accessible to everyone.We also believe that having a status page is essential for your users to know the status of your services.-We also think that manually updating your status page is a waste of time. The best way to update your status page is to automate it. That's why we built OpenStatus.+We also think that manually updating your status page is a waste of time. The best way to update your status page is to automate it. That's why we built openstatus.-In this guide, we will show you how to deploy your own status page to Cloudflare Pages using OpenStatus monitoring data.+In this guide, we will show you how to deploy your own status page to Cloudflare Pages using openstatus monitoring data.For the Status Page, we will use [Astro](https://astro.build/) a new JavaScript web framework, that allows you to build faster websites with less JavaScript.@@ -32,29 +32,29 @@ The code showcased in this guide is available on [GitHub](https://github.com/opeTo follow this guide, you need:- A Cloudflare Account.-- An [OpenStatus](https://www.openstatus.dev) Account.+- An [openstatus](https://www.openstatus.dev) Account.## Start monitoring your services-To get your monitoring data, you need to create a monitor on OpenStatus.+To get your monitoring data, you need to create a monitor on openstatus.We will monitor the status of your endpoint and get the data to display on your status page.### How to create a monitorTo create a monitor, follow these steps:-1. Go to the OpenStatus dashboard.+1. Go to the openstatus dashboard.2. Click on the `Monitors` tab.3. Click on the `Create Monitor` button.4. Fill in the form with your endpoint details.5. Click on the `Create Monitor` button.-### Get your OpenStatus API key+### Get your openstatus API keyTo get your API key, follow these steps:-1. Go to the OpenStatus dashboard.+1. Go to the openstatus dashboard.2. Click on the `Settings` tab.3. Click on the `API Token` tab.4. Click on the `Create API Key` button.@@ -62,14 +62,14 @@ To get your API key, follow these steps:## Deploy your own status page-With OpenStatus monitoring data, you can bring your status page to life. You can really make it your own.+With openstatus monitoring data, you can bring your status page to life. You can really make it your own.We are going to deploy a simple status page that shows the status of your endpoint.For this guide we are going to use our [Astro Status Page](https://github.com/openstatusHQ/astro-status-page) template.### Customize the Astro Status Page-In the `index.astro` we are fetching the monitor data from OpenStatus and displaying it on the page.+In the `index.astro` we are fetching the monitor data from openstatus and displaying it on the page.```tsconst response = await fetch("https://api.openstatus.dev/v1/monitor", {@@ -99,7 +99,7 @@ Go to your Cloudflare dashboard and click on the `Workers & Pages`.Select your site and click on the `Settings` tab.-You can add your OpenStatus API key as an environment variable.+You can add your openstatus API key as an environment variable.```envAPI_KEY=your-api-key@@ -111,4 +111,4 @@ Now you can deploy your Astro Status Page to Cloudflare Pages with the followingnpm run pages:deploy```-Your Status Page is now live on Cloudflare Pages. 🎉\ No newline at end of file+Your Status Page is now live on Cloudflare Pages. 🎉diff --git a/apps/docs/src/content/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx b/apps/docs/src/content/docs/guides/how-to-deploy-probes-cloudflare-containers.mdxindex acb780e18..1cda48af2 100644--- a/apps/docs/src/content/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx+++ b/apps/docs/src/content/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx@@ -1,6 +1,6 @@---title: How to deploy the openstatus probe to Cloudflare Containers-description: Learn how to use OpenStatus monitoring data and deploy your own Status Page to cloudflare pages.+description: Learn how to use openstatus monitoring data and deploy your own Status Page to cloudflare pages.sidebar:label: Deploy private probes on Cloudflare Containers---@@ -9,7 +9,7 @@ import log from '../../../assets/guides/how-to-deploy-probes-cf-containters/clouimport os from '../../../assets/guides/how-to-deploy-probes-cf-containters/private-location.jpg';-In this guide we will show you how to deploy the OpenStatus probe to Cloudflare Containers.+In this guide we will show you how to deploy the openstatus probe to Cloudflare Containers.Cloudflare Containers is a platform that allows you to run serverless containers in the Cloudflare network.@@ -23,9 +23,9 @@ The code showcased in this guide is available on [GitHub](https://github.com/ope-### Create a private location on OpenStatus+### Create a private location on openstatus-1. Go to the OpenStatus dashboard.+1. Go to the openstatus dashboard.2. Click on the `Private locations` in the sidebar.3. Click on the `Create Private Location` button.4. Give it a human readable name.@@ -95,7 +95,7 @@ async scheduled(_controller: any, env: Env) {},```-9. Add you OpenStatus API secret+9. Add you openstatus API secret```bashpnpm wrangler secret put OPENSTATUS_KEY@@ -118,11 +118,11 @@ You have successfully deployed the openstatus private location probe to Cloudfla<Imagesrc={log}- alt="OpenStatus Private Location on Cloudflare Containers"- caption="Cloudflare Workers Logs showing OpenStatus Private Location running"+ alt="openstatus Private Location on Cloudflare Containers"+ caption="Cloudflare Workers Logs showing openstatus Private Location running"/><Imagesrc={os}- alt="OpenStatus Private Location on Cloudflare Containers"+ alt="openstatus Private Location on Cloudflare Containers"/>diff --git a/apps/docs/src/content/docs/guides/how-to-monitor-mcp-server.mdx b/apps/docs/src/content/docs/guides/how-to-monitor-mcp-server.mdxindex ffaf8693c..f9e859864 100644--- a/apps/docs/src/content/docs/guides/how-to-monitor-mcp-server.mdx+++ b/apps/docs/src/content/docs/guides/how-to-monitor-mcp-server.mdx@@ -1,45 +1,46 @@----title: How to monitor your Model Context Provider (MCP) server?-description: Learn how to monitor your MCP server with openstatus.+title: How to Monitor Your Model Context Provider (MCP) Server+description: Learn how to monitor your MCP server with openstatus using JSON-RPC ping checkssidebar:label: Monitor your MCP Server----In this guide, we will show you how to monitor your remote MCP server using OpenStatus. We will use the Hugging Face MCP server for this article, but you can apply the same principles to any MCP server. You can find the code for this guide on [GitHub](https://github.com/openstatusHQ/template/tree/a69eac06e9d3d8579768dad803304e456f56ec33/mcp-server).-**Prerequisites**+## Problem: Ensuring Your MCP Server is Always Responsive-- An OpenStatus account and CLI-- An MCP server+Running a Model Context Provider (MCP) server is critical for your AI applications, but traditional HTTP monitoring often falls short. MCP servers communicate using the JSON-RPC 2.0 protocol, requiring specific request/response patterns that standard health checks don't cover. How can you confidently ensure your MCP server is healthy and responsive at all times, without custom scripts or complex setups?-## Model Context Provider (MCP)+## Solution: JSON-RPC Ping Monitoring with openstatus-A Model Context Provider is a component that supplies additional context, data, or capabilities to AI models during runtime through the Model Context Protocol (MCP). It acts as a bridge, allowing AI models to access external resources such as databases, APIs, file systems, or other services not included in their original training data.+openstatus offers a robust solution for monitoring your MCP servers. By sending precise JSON-RPC `ping` requests to your endpoint from multiple global locations, openstatus verifies not only network reachability but also the correct functioning of your server's JSON-RPC interface. This guide will walk you through setting up comprehensive monitoring for any MCP server using the openstatus CLI.-### What is an MCP Server?+## Prerequisites-The server component of the MCP protocol hosts and manages external resources, tools, or data sources that AI models can access. It handles incoming requests from MCP clients, processes them according to the protocol specifications, and returns the requested information or executes the specified actions. The MCP server serves as the backend provider, exposing capabilities like database queries, file operations, or API calls in a standardized format for AI models to interact with.+Before you begin, ensure you have:-The protocol must adhere to the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification).+- An [openstatus account](https://www.openstatus.dev/app/login).+- The [openstatus CLI installed](/tutorial/get-started-with-openstatus-cli). (If you haven't installed it yet, follow this guide first).+- An MCP server with a publicly accessible endpoint.+- A basic understanding of the [JSON-RPC 2.0 protocol](https://www.jsonrpc.org/specification).-### JSON-RPC Protocol+## Background: Understanding MCP for Monitoring-JSON-RPC is a remote procedure call protocol that uses JSON as its data format. It is designed to be simple and easy to implement while providing a robust and flexible way to communicate between clients and servers. The JSON-RPC protocol is transport-independent, but for MCP servers, it uses HTTP/HTTPS, making it easy to monitor with OpenStatus.+A Model Context Provider (MCP) is a crucial component that extends AI models with external context, data, or capabilities via the **Model Context Protocol (MCP)**. Essentially, it acts as a bridge, allowing AI models to interact with resources like databases, APIs, or file systems that aren't part of their core training.-### Ping Utility+### The MCP Server and JSON-RPC 2.0-The official [MCP documentation](https://modelcontextprotocol.io/docs/concepts/architecture#debugging-and-monitoring) recommends implementing a health check for your MCP server. The protocol includes a mechanism to verify that the server is still responsive: the ping utility. The ping feature operates using a basic request/response mechanism.+The MCP server is the backend component that hosts these external resources. It processes incoming requests from MCP clients, executes specified actions, and returns information according to the [JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification). JSON-RPC is a lightweight remote procedure call protocol using JSON for data exchange. While transport-independent, MCP servers typically use HTTP/HTTPS, making them readily monitorable by openstatus.-## Create Your OpenStatus Monitor+### The Ping Utility: Health Check Standard- OpenStatus allows you to monitor your MCP server by sending a ping request to your MCP server's endpoint on a regular basis from multiple locations around the world. Making it easy to monitor your remote MCP server's health and performance.+For robust monitoring, the official [MCP documentation](https://modelcontextprotocol.io/docs/concepts/architecture#debugging-and-monitoring) recommends implementing a health check using the **ping utility**. This simple request/response mechanism verifies the server's responsiveness and is the foundation for our openstatus monitor.-### YAML Configuration+## Create Your openstatus Monitor: YAML Configuration-The [OpenStatus CLI](/tutorial/get-started-with-openstatus-cli) allows you to create monitor defined in a YAML configuration file. This is perfect solution if want to manage your monitors via GitOps.+openstatus allows you to define and manage your monitors using YAML configuration files, a perfect solution for GitOps workflows. This approach ensures your monitoring setup is version-controlled, auditable, and easily deployable via the openstatus CLI.-Here's an example of a monitor configuration for Hugging Face MCP server:+Here's an example of a monitor configuration for a Hugging Face MCP server, which you can adapt for your own MCP endpoint:-```YAML+```yaml# yaml-language-server: $schema=https://www.openstatus.dev/schema.jsonmcp-server:@@ -60,7 +61,7 @@ mcp-server:"method": "ping"}headers:- User-Agent: OpenStatus+ User-Agent: openstatusAccept: application/json, text/event-streamContent-Type: application/jsonassertions:@@ -72,48 +73,88 @@ mcp-server:target: '{"result":{},"jsonrpc":"2.0","id":"openstatus"}'```-### What Does This Monitor Do?+### Understanding the Configuration++Let's break down the key fields in this YAML configuration:++- `name`: A human-readable name for your monitor (e.g., "HF MCP Server").+- `description`: A brief explanation of what this monitor checks.+- `frequency`: How often openstatus will run the check. Common values include `30s`, `1m`, `5m`, `10m`, `30m`, `1h`. Setting a sensible frequency balances timely alerts with resource usage.+- `active`: Set to `true` to enable the monitor, `false` to disable it.+- `regions`: An array of geographic regions from which openstatus will perform the checks (e.g., `["iad", "ams", "lax"]` for North America, Europe, and West US). Monitoring from multiple regions helps detect localized issues.+- `retry`: The number of times openstatus will retry a failed check before marking it as genuinely down. This helps prevent false positives due to transient network issues.+- `kind`: Specifies the type of monitor. For MCP servers using HTTP/HTTPS, this will be `http`.+- `request`:+ - `url`: The full URL of your MCP server's JSON-RPC endpoint.+ - `method`: The HTTP method, which should be `POST` for JSON-RPC requests.+ - `body`: The JSON-RPC `ping` request payload. The `"method": "ping"` is crucial for triggering the health check on your MCP server.+ ```json+ {+ "jsonrpc": "2.0",+ "id": "openstatus",+ "method": "ping"+ }+ ```+ - `headers`: Standard HTTP headers for JSON-RPC communication.+- `assertions`: Rules to validate the response from your MCP server. These are critical for determining if the server is healthy.+ - **Status Code Check**: `statusCode` assertion ensures the HTTP response is `200` (OK).+ ```yaml+ - kind: statusCode+ compare: eq+ target: 200+ ```+ - **Response Body Check**: `textBody` assertion verifies that the response payload matches the expected JSON-RPC `ping` result. The `target` value must precisely match the successful `ping` response from your MCP server.+ ```yaml+ - kind: textBody+ compare: eq+ target: '{"result":{},"jsonrpc":"2.0","id":"openstatus"}'+ ```++### Testing Your MCP Server (Optional)++Before deploying your openstatus monitor, it's a good practice to manually test your MCP server's `ping` endpoint using `curl` to ensure it responds as expected. This helps in debugging and confirming the `target` value for your `textBody` assertion.-We send an HTTP POST request to the MCP server. The request body contains a JSON-RPC request with the method "ping".--```json-{- "jsonrpc": "2.0",- "id": "openstatus",- "method": "ping"-}+```bash+curl -X POST \\+ -H "Content-Type: application/json" \\+ -d '{"jsonrpc": "2.0", "id": "openstatus", "method": "ping"}' \\+ https://hf.co/mcp # Replace with your MCP server URL```-We set our headers to accept `application/json` and `text/event-stream`. We also include assertions to verify the response.+This command should return a JSON response similar to `{"result":{},"jsonrpc":"2.0","id":"openstatus"}` if your MCP server is healthy and correctly implements the `ping` utility.-First, we check that the status code is 200.+### Using openstatus CLI to Create Your Monitor-```YAML- - kind: statusCode- compare: eq- target: 200+Once your `openstatus.yaml` file is ready, create your monitor using the openstatus CLI:++```bash+openstatus create openstatus.yaml```-Next, we verify that the response body is correct.+This command will upload your monitor configuration to openstatus, and monitoring will begin according to the specified `frequency` and `regions`.-```YAML- - kind: textBody- compare: eq- target: '{"result":{},"jsonrpc":"2.0","id":"openstatus"}'-```+## Conclusion: Comprehensive MCP Server Monitoring Achieved-### Using OpenStatus CLI to Create Your Monitor+This guide has equipped you with the knowledge to effectively monitor your MCP server using openstatus. By leveraging YAML configuration and the openstatus CLI, you can ensure your critical AI infrastructure remains healthy and responsive.-To create your monitor, use the OpenStatus CLI.+## What You've Accomplished-```bash-openstatus create openstatus.yaml-```+- ✅ Successfully configured a JSON-RPC based monitor for your MCP server.+- ✅ Implemented precise assertions to validate `ping` responses.+- ✅ Set up global monitoring to detect localized or widespread issues.+- ✅ Automated monitor deployment using a version-controlled YAML configuration.++## Next Steps-## Conclusion+Now that your MCP server is under robust monitoring, consider further enhancing your setup:-This guide has shown you how to create a monitor for your MCP server using the OpenStatus CLI. You can view the monitor in the OpenStatus dashboard.+- **[Set up Alerting](/monitoring/customization/notification)**: Configure notifications to be immediately informed of any MCP server downtime or performance degradation.+- **[Export Metrics to OTLP](/guides/how-to-export-metrics-to-otlp-endpoint)**: Integrate your MCP monitoring data with your existing observability platform for centralized analytics.+- **[Run Synthetic Tests in GitHub Actions](/guides/how-to-run-synthetic-test-github-action/)**: Incorporate these synthetic checks into your CI/CD pipeline for pre-deployment validation.-For example, here is our monitor for the HF MCP server:+## Related Resources-[https://www.openstatus.dev/public/monitors/5961](https://www.openstatus.dev/public/monitors/5961)+- **[JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)**: Deep dive into the JSON-RPC protocol.+- **[MCP Official Documentation](https://modelcontextprotocol.io/docs/concepts/architecture#debugging-and-monitoring)**: Official insights into MCP health checks.+- **[HTTP Monitor Reference](/reference/http-monitor)**: Comprehensive API reference for HTTP monitors.+- **[CLI Reference](/reference/cli-reference)**: Full documentation for the openstatus CLI.diff --git a/apps/docs/src/content/docs/guides/how-to-run-synthetic-test-github-action.mdx b/apps/docs/src/content/docs/guides/how-to-run-synthetic-test-github-action.mdxindex 80971bb19..fe35bf62f 100644--- a/apps/docs/src/content/docs/guides/how-to-run-synthetic-test-github-action.mdx+++ b/apps/docs/src/content/docs/guides/how-to-run-synthetic-test-github-action.mdx@@ -1,21 +1,30 @@----title: How to run a synthetic test in a GitHub Action-description: Learn how to run a synthetic test in a GitHub Action using OpenStatus.+title: How to Run Synthetic Tests in GitHub Actions+description: Integrate openstatus synthetic monitoring into your CI/CD pipelinesidebar:- label: GitHub Action for Synthetics Tests+ label: GitHub Action for Synthetics----In this guide, we will show you how to run a synthetic test in a GitHub Action using OpenStatus.+## Problem-### Requirements+You want to validate that your application's critical endpoints are working before deploying to production. Running synthetic tests in your CI/CD pipeline catches issues early and prevents broken deployments.-- An [OpenStatus](https://www.openstatus.dev) Account .-- A GitHub Repository.+## Solution-### Create a configuration file+openstatus provides a GitHub Action that runs your configured monitors as part of your CI/CD workflow. This guide shows you how to set it up.-First, you need to create a configuration file for your synthetic test.+## Prerequisites+- An [openstatus](https://www.openstatus.dev) account+- A GitHub repository+- At least one monitor configured in openstatus+- Admin access to your GitHub repository (for secrets)++## Step-by-step guide++### 1. Create a configuration file++Create a file named `openstatus.config.yaml` in your repository root:```yamltests:@@ -23,46 +32,144 @@ tests:- 1- 2```-The ids are the ids of the monitors you want to run. You can find the ids in the URL of the monitor page.+**Finding monitor IDs:**+1. Go to your openstatus dashboard+2. Click on a monitor+3. The ID is in the URL: `https://www.openstatus.dev/app/[workspace]/monitors/[ID]`-### Get your OpenStatus API Key+**Tip:** Start with your most critical monitors and expand from there.-You can find your API key in the settings page of your OpenStatus account.-Go to the settings page and copy your API key.+### 2. Get your openstatus API key+1. Go to your openstatus workspace settings+2. Navigate to the API section+3. Create a new API key or copy an existing one+4. Store it securely - you'll need it for the next step+### 3. Add your API key to GitHub Secrets-### Add your API Key to GitHub Secrets+Secure your API key as a GitHub secret:-Go to the settings of your repository and add a new secret with the name `OPENSTATUS_API_KEY` and the value of your OpenStatus API key.+1. Go to your GitHub repository+2. Click **Settings** → **Secrets and variables** → **Actions**+3. Click **New repository secret**+4. Name: `OPENSTATUS_API_KEY`+5. Value: Your openstatus API key+6. Click **Add secret**+### 4. Create the GitHub Action workflow-### Create a GitHub Action--Create a new file in your repository under `.github/workflows` with the following content:+Create `.github/workflows/openstatus.yml`:```yaml-name: Run OpenStatus Synthetics CI+name: Run openstatus Synthetics CIon:- workflow_dispatch:+ workflow_dispatch: # Manual triggerpush:- branches: [ main ]+ branches: [ main ] # Trigger on push to main+ pull_request: # Run on PRs (optional)jobs:synthetic_ci:runs-on: ubuntu-latest- name: Run OpenStatus Synthetics CI+ name: Run openstatus Synthetics CIsteps:- name: Checkoutuses: actions/checkout@v4- - name: Run OpenStatus Synthetics CI++ - name: Run openstatus Synthetics CIuses: openstatushq/openstatus-github-action@v1with:api_key: ${{ secrets.OPENSTATUS_API_KEY }}```-### Run the GitHub Action+### 5. Commit and push++```bash+git add openstatus.config.yaml .github/workflows/openstatus.yml+git commit -m "Add openstatus synthetic tests to CI"+git push origin main+```++The GitHub Action will run automatically on the next push to `main`.++## What you've accomplished++Great work! You've successfully:+- ✅ Integrated openstatus into your CI/CD pipeline+- ✅ Automated synthetic testing on every deployment+- ✅ Added a safety check before production releases+- ✅ Set up continuous validation of critical endpoints++## Customization options++### Run on different branches++```yaml+on:+ push:+ branches: [ main, staging, develop ]+```++### Run on pull requests++```yaml+on:+ pull_request:+ types: [opened, synchronize, reopened]+```++### Run on a schedule++```yaml+on:+ schedule:+ - cron: '0 */4 * * *' # Every 4 hours+```++### Multiple configuration files++```yaml+- name: Run openstatus Synthetics CI+ uses: openstatushq/openstatus-github-action@v1+ with:+ api_key: ${{ secrets.OPENSTATUS_API_KEY }}+ config_file: .openstatus/production.yaml+```++## Best practices++1. **Start small**: Begin with 2-3 critical monitors+2. **Fail fast**: Run synthetic tests early in your pipeline+3. **Monitor the monitors**: Track your synthetic test success rate+4. **Environment-specific**: Use different monitors for staging vs production+5. **Document failures**: Investigate and document any CI failures++## Troubleshooting++**Action fails with authentication error:**+- Verify `OPENSTATUS_API_KEY` secret is set correctly+- Check that your API key hasn't expired++**Monitors not found:**+- Confirm monitor IDs are correct in `openstatus.config.yaml`+- Ensure monitors are active in your openstatus dashboard++**Tests timing out:**+- Check that your endpoints are accessible from GitHub's runners+- Consider increasing timeouts in monitor configuration++## Next steps++- **[Monitor Your MCP Server](/guides/how-to-monitor-mcp-server/)** - Advanced monitoring examples+- **[Monitoring as Code](/concept/uptime-monitoring-as-code)** - Manage monitors with YAML+- **[CLI Reference](/reference/cli-reference)** - Automate monitor management+- **[Export Metrics](/guides/how-to-export-metrics-to-otlp-endpoint)** - Send data to your observability platform++## Related resources-On every push to the main branch, the GitHub Action will run the synthetic tests you have configured in the configuration file.+- **[GitHub Action on Marketplace](https://github.com/marketplace/actions/openstatus-synthetics-ci)** - Official action+- **[Example Repository](https://github.com/openstatusHQ/github-action-example)** - Working examples+- **[Join Discord](https://www.openstatus.dev/discord)** - Get help from the communitydiff --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.mdxindex 967a921e2..f3b98283f 100644--- 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@@ -1,5 +1,5 @@----title: How to Use OpenStatus React Widget+title: How to Use openstatus React Widget---Install the [npm](https://www.npmjs.com/package/@openstatus/react) package:diff --git a/apps/docs/src/content/docs/guides/self-hosting-openstatus.mdx b/apps/docs/src/content/docs/guides/self-hosting-openstatus.mdxindex 42f6df126..fa6606c02 100644--- a/apps/docs/src/content/docs/guides/self-hosting-openstatus.mdx+++ b/apps/docs/src/content/docs/guides/self-hosting-openstatus.mdx@@ -1,111 +1,189 @@----title: How to self host openstatus-description: Learn how to self host openstatus in your own infra.+title: How to Self-Host openstatus+description: Complete guide to deploying openstatus on your own infrastructure---+import { Image } from 'astro:assets';import localOpenstatus from '../../../assets/guides/self-hosting-openstatus/local-openstatus.png';+## Problem++You want to run openstatus on your own infrastructure instead of using the hosted service. This gives you full control over your data, customization options, and the ability to monitor internal services not accessible from the public internet.++## Solution-If you want to self host openstatus, we provide a [docker-compose](https://github.com/openstatusHQ/openstatus/blob/2aa970b7fc2afaca5e3ec584beda69c1f69ca34d/docker-compose.yaml) file to get you started quickly.+openstatus provides a Docker Compose setup that makes self-hosting straightforward. This guide walks you through deploying all necessary services and configuring your self-hosted instance.+## Prerequisites++- Docker and Docker Compose installed+- Basic understanding of Docker and containerization+- Command line experience+- Git installed+- Node.js and pnpm (for database migrations)## Known limitations-- It only works with private locations. You have to deploy our probes to the cloud provider of your choice.+Self-hosting openstatus currently has these constraints:++- It only works with private locations. You have to deploy our probes to the cloud provider of your choice.++## Step-by-step guide-## Get started+This guide is divided into three parts: launching the services, setting up the database and analytics, and configuring the application through the UI.-1. Clone the repository+### Part 1: Initial Setup and Service Launch-```bash-git clone-```+1. **Clone the Repository**-2. Copy the `.env.example` file to `.env` and modify the environment variables as needed.+ Get the latest version of openstatus:+ ```bash+ git clone https://github.com/openstatushq/openstatus+ cd openstatus+ ```-```bash-cp .env.docker.example .env.docker-```+2. **Configure Your Environment**-3. Build the containers-```-export DOCKER_BUILDKIT=1-docker compose up -d-```+ Copy the example environment file. This file will hold all your configuration variables.+ ```bash+ cp .env.docker.example .env.docker+ ```+ Open `.env.docker` in a text editor. At a minimum, you **must** set a value for `AUTH_SECRET` for authentication to work. For a complete setup, review the file for other variables like OAuth providers or email services.-4. Migrate the database+3. **Build and Start Services**-```bash-cd packages/db-pnpm migrate-```+ Use Docker Compose to build and run all openstatus services in the background.+ ```bash+ export DOCKER_BUILDKIT=1+ docker compose up -d+ ```+ You can check the status of the services with `docker compose ps`. It might take a few minutes for all services to be healthy.-5. Create Tinybird datasources, pipes and endpoints+### Part 2: Database and Analytics Setup-```bash-cd packages/tinybird-tb --local deploy-```+4. **Run Database Migrations**-7. Access Tinybird local UI and get your TOKEN+ The database container starts with an empty database. You must run migrations to set up the required schema.+ ```bash+ # Make sure you are in the root of the openstatus project+ cd packages/db+ pnpm install+ pnpm migrate+ cd ../.. # Return to the project root+ ```-```bash-tb --local open-```+5. **Deploy Local Tinybird Analytics**-8. Update the `.env.docker` file with your Tinybird TOKEN+ Tinybird is used for analytics. Deploy the local datasources, pipes, and endpoints.+ ```bash+ # Make sure you are in the root of the openstatus project+ cd packages/tinybird+ pnpm install+ tb --local deploy+ cd ../.. # Return to the project root+ ```-9. Connect to your OpenStatus instance and create a new workspace.+6. **Configure Tinybird API Key**-10. Update your newly created workspace with the following limits:+ You need to get your local Tinybird admin token and add it to your environment file.+ ```bash+ cd packages/tinybird+ tb --local open # This opens the Tinybird UI in your browser+ ```+ In the Tinybird UI, find and copy your admin token. Then, add it to your `.env.docker` file in the root of the project:+ ```env+ TINY_BIRD_API_KEY="your-tinybird-admin-token"+ ```+ After adding the token, restart your services for the changes to take effect:+ ```bash+ # Make sure you are in the root of the openstatus project+ docker compose restart+ ```-```json-{- "monitors": 100,- "periodicity": ["30s", "1m", "5m", "10m", "30m", "1h"],- "multi-region": true,- "data-retention": "24 months",- "status-pages": 20,- "maintenance": true,- "status-subscribers": true,- "custom-domain": true,- "password-protection": true,- "white-label": true,- "notifications": true,- "sms": true,- "pagerduty": true,- "notification-channels": 50,- "members": "Unlimited",- "audit-log": true,- "private-locations": true-}-```+### Part 3: Application Configuration-11. Create a new private location in the dashboard.+Now that the services are running, you can access the dashboard and perform the final setup steps.-12. Deploy the private location to your cloud provider of choice with your location api key `OPENSTATUS_KEY`, and `OPENSTATUS_INGEST_URL` .+- **Dashboard:** `http://localhost:3002`+- **Status Pages:** `http://localhost:3003`-The docker image of the private location is `ghcr.io/openstatushq/private-location:latest`+7. **Create a Workspace and Set Limits**-13. Create monitors and start monitoring your services!+ - Navigate to the dashboard at `http://localhost:3002`.+ - Sign up and create a new workspace.+ - Because this is a self-hosted instance, you need to manually set the feature limits for your workspace directly in the database.++ The following command updates the limits for the workspace with `id = 1`. If your workspace has a different ID, change the `WHERE id = 1` part of the command.+ ```bash+ curl -X POST http://localhost:8080/ -H "Content-Type: application/json" \+ -d '{"statements":["UPDATE workspace SET limits = '\''{\\"monitors\\":100,\\"periodicity\\":[\\"30s\\",\\"1m\\",\\"5m\\",\\"10m\\",\\"30m\\",\\"1h\\"],\\"multi-region\\":true,\\"data-retention\\":\\"24 months\\",\\"status-pages\\":20,\\"maintenance\\":true,\\"status-subscribers\\":true,\\"custom-domain\\":true,\\"password-protection\\":true,\\"white-label\\":true,\\"notifications\\":true,\\"sms\\":true,\\"pagerduty\\":true,\\"notification-channels\\":50,\\"members\\":\\"Unlimited\\",\\"audit-log\\":true,\\"private-locations\\":true}'\'' WHERE id = 1"]}'+ ```+ You can find your workspace ID by inspecting the database with a command like `curl -X POST http://localhost:8080/ -H "Content-Type: application/json" -d '{"statements":["SELECT id, name FROM workspace"]}'`.++8. **Deploy a Private Location**++ The self-hosted version relies on private locations to perform checks.+ - In the dashboard, navigate to **Settings -> Private Locations** and create a new one.+ - Copy the generated `OPENSTATUS_KEY`.+ - Deploy the private location probe to your infrastructure using the Docker image `ghcr.io/openstatushq/private-location:latest`.+ - When deploying, you must provide two environment variables to the container:+ - `OPENSTATUS_KEY`: The key you just copied.+ - `OPENSTATUS_INGEST_URL`: The URL of your self-hosted server's API endpoint (e.g., `http://<your-server-ip-or-domain>:3001`).+ - For a detailed guide on deploying a private location, see **[Deploy Private Locations on Cloudflare Containers](/guides/how-to-deploy-probes-cloudflare-containers)**.++9. **Create Monitors**++ You're all set! You can now create monitors in the dashboard. They will be checked by the private location you deployed.<Imagesrc={localOpenstatus}- alt="Openstatus running locally"+ alt="openstatus running locally with self-hosted services"/>-## Our services Services+## Service architecture++openstatus consists of multiple services running together:| Service | Port | Purpose ||---------|------|---------|-| workflows | 3000 | Background jobs |+| workflows | 3000 | Background jobs and scheduled tasks || server | 3001 | API backend (tRPC) |-| dashboard | 3002 | Admin interface |+| dashboard | 3002 | Admin interface for configuration || status-page | 3003 | Public status pages |-| private-location | 8081 | Monitoring agent |+| private-location | 8081 | Monitoring agent for checks || libsql | 8080 | Database (HTTP) || libsql | 5001 | Database (gRPC) |-| tinybird-local | 7181 | Analytics |+| tinybird-local | 7181 | Analytics and metrics |++## What you've accomplished++Congratulations! You've successfully:+- ✅ Deployed openstatus on your own infrastructure+- ✅ Configured all required services+- ✅ Set up a private location for monitoring+- ✅ Created your first self-hosted monitor++## Troubleshooting++**Containers won't start**: Check Docker logs with `docker compose logs [service-name]`++**Database migrations fail**: Ensure you're in the correct directory and have pnpm installed++**Private location not connecting**: Verify the `OPENSTATUS_KEY` and `OPENSTATUS_INGEST_URL` are correct++**Tinybird issues**: Make sure the Tinybird token is correctly set in `.env.docker`++## Next steps++- **[Deploy Private Locations](/guides/how-to-deploy-probes-cloudflare-containers)** - Set up monitoring from multiple regions+- **[Create Monitors](/tutorial/how-to-create-monitor)** - Start monitoring your services+- **[Configure Notifications](/monitoring/customization/notification)** - Get alerted on issues++## Additional resources++- **[Docker Compose file](https://github.com/openstatusHQ/openstatus/blob/main/docker-compose.yaml)** - Review the complete configuration+- **[Private Location Reference](/reference/private-location)** - Technical specifications+- **[Join our Discord](https://www.openstatus.dev/discord)** - Get help from the communitydiff --git a/apps/docs/src/content/docs/incident/incident-detail.mdx b/apps/docs/src/content/docs/incident/incident-detail.mdxdeleted file mode 100644index 32af80e44..000000000--- a/apps/docs/src/content/docs/incident/incident-detail.mdx+++ /dev/null@@ -1,21 +0,0 @@-----title: Incident Detail-description: "Discover the incident details in OpenStatus"-order: 2------import { Image } from 'astro:assets';-import IncidentDetail from '../../../assets/incident/incident-detail.png';-import { Aside } from '@astrojs/starlight/components';---On the incident page, you can see the details of the incident, the monitor that failed, and the duration.-We are also taking a screenshot of the monitor when the incident is created, and when it's resolved.--- <Image- src={IncidentDetail}- alt="Incident page"- />--<Aside>There might be a delay between the incident creation and the screenshot capture. Your endpoint could have already recovered.</Aside>\ No newline at end of filediff --git a/apps/docs/src/content/docs/incident/overview.mdx b/apps/docs/src/content/docs/incident/overview.mdxdeleted file mode 100644index e622083e5..000000000--- a/apps/docs/src/content/docs/incident/overview.mdx+++ /dev/null@@ -1,11 +0,0 @@-----title: Overview-description: "Discover what is an incident in OpenStatus"-------## 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.diff --git a/apps/docs/src/content/docs/incident/work-with-incident.mdx b/apps/docs/src/content/docs/incident/work-with-incident.mdxdeleted file mode 100644index 0f6c29171..000000000--- a/apps/docs/src/content/docs/incident/work-with-incident.mdx+++ /dev/null@@ -1,25 +0,0 @@-----title: Work with Incidents-description: "How to acknowledge and resolve incidents in OpenStatus"------An incident can have the following states:--- **On Going**: The incident is still active.-- **Acknowledged**: The incident has been acknowledged.-- **Resolved**: The incident has been resolved.--## 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/src/content/docs/index.mdx b/apps/docs/src/content/docs/index.mdxindex 9fe87ac32..4f06731b8 100644--- a/apps/docs/src/content/docs/index.mdx+++ b/apps/docs/src/content/docs/index.mdx@@ -14,18 +14,24 @@ import "../../custom.css"### What is openstatus?-[openstatus](https://www.openstatus.dev) is an open-source status page platform with uptime monitoring.+[openstatus](https://www.openstatus.dev) is an open-source status page platform with uptime monitoring. Monitor your websites, APIs, and services from multiple global locations and share real-time status updates with your users.-### New to openstatus?+### How to use this documentation+Our documentation follows the [Diátaxis framework](https://diataxis.fr/), organizing content into four distinct categories to help you find what you need:<CardGrid >- <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?" />+ <LinkCard title="📚 Tutorials" href="/tutorial/getting-started/" description="Step-by-step lessons to learn openstatus from scratch. Start here if you're new!" />+ <LinkCard title="🛠️ How-to Guides" href="/guides/getting-started/" description="Practical guides to solve specific problems and accomplish particular tasks." />+ <LinkCard title="💡 Concepts" href="/concept/getting-started/" description="In-depth explanations of key concepts, design decisions, and best practices." />+ <LinkCard title="📖 Reference" href="/reference" description="Technical specifications, API documentation, and configuration references." /></CardGrid>+**Not sure where to start?**+- **New users**: Begin with our [tutorials](/tutorial/getting-started/) to create your first monitor+- **Experienced users**: Check out [how-to guides](/guides/getting-started/) for specific tasks+- **Need help?** Visit our [help section](/help/support/) or join our community+### Join the communitydiff --git a/apps/docs/src/content/docs/monitoring/clone-monitor.mdx b/apps/docs/src/content/docs/monitoring/clone-monitor.mdxindex 19c1a10b5..4e9cc0328 100644--- a/apps/docs/src/content/docs/monitoring/clone-monitor.mdx+++ b/apps/docs/src/content/docs/monitoring/clone-monitor.mdx@@ -1,6 +1,6 @@---title: How to clone a monitor?-description: "How to clone a monitor with OpenStatus"+description: "How to clone a monitor with openstatus"---import { Image } from 'astro:assets';diff --git a/apps/docs/src/content/docs/monitoring/customization/assertions.mdx b/apps/docs/src/content/docs/monitoring/customization/assertions.mdxindex f1db24b74..35a6977d4 100644--- a/apps/docs/src/content/docs/monitoring/customization/assertions.mdx+++ b/apps/docs/src/content/docs/monitoring/customization/assertions.mdx@@ -1,6 +1,6 @@---title: Assertions-description: "How to set up assertions for your synthetic checks in OpenStatus"+description: "How to set up assertions for your synthetic checks in openstatus"---diff --git a/apps/docs/src/content/docs/monitoring/customization/follow-redirects.mdx b/apps/docs/src/content/docs/monitoring/customization/follow-redirects.mdxindex ed953ad5a..85f28ae51 100644--- a/apps/docs/src/content/docs/monitoring/customization/follow-redirects.mdx+++ b/apps/docs/src/content/docs/monitoring/customization/follow-redirects.mdx@@ -1,6 +1,6 @@---title: Follow Redirects-description: "What are follow redirects on a monitor in OpenStatus"+description: "What are follow redirects on a monitor in openstatus"---The Follow Redirects option controls whether your monitor should automatically follow HTTP redirects. **By default, we follow the redirects.**@@ -9,4 +9,4 @@ When enabled, the monitor will follow any `3xx` redirect responses (e.g. `301 MoEnable this option if:- You are monitoring a URL that often redirects (e.g. from http:// to https://, or from a short link to the final page).-- You want to verify that the final destination is available and returns the expected response.\ No newline at end of file+- You want to verify that the final destination is available and returns the expected response.diff --git a/apps/docs/src/content/docs/monitoring/customization/frequency.mdx b/apps/docs/src/content/docs/monitoring/customization/frequency.mdxindex fefbc527d..7f1ee48a1 100644--- a/apps/docs/src/content/docs/monitoring/customization/frequency.mdx+++ b/apps/docs/src/content/docs/monitoring/customization/frequency.mdx@@ -1,9 +1,9 @@---title: Frequency-description: "How to change the frequency of your synthetic checks in OpenStatus"+description: "How to change the frequency of your synthetic checks in openstatus"----By default, OpenStatus.dev will check your service every 30 minutes.+By default, openstatus.dev will check your service every 30 minutes.The min frequency options range from 10 minutes for free plans to 30 seconds for paid plans.diff --git a/apps/docs/src/content/docs/monitoring/customization/locations.mdx b/apps/docs/src/content/docs/monitoring/customization/locations.mdxindex 2a186659e..3713f303a 100644--- a/apps/docs/src/content/docs/monitoring/customization/locations.mdx+++ b/apps/docs/src/content/docs/monitoring/customization/locations.mdx@@ -1,6 +1,6 @@---title: Locations-description: "How to change the locations for your synthetic checks in OpenStatus"+description: "How to change the locations for your synthetic checks in openstatus"---@@ -8,7 +8,7 @@ We have multiple locations around the world to monitor your services. You can ch## Public Locations-For free users, OpenStatus will monitor your service from six location, one on every continent. For paid users, you can choose from multiple locations around the world to monitor your service.+For free users, openstatus will monitor your service from six location, one on every continent. For paid users, you can choose from multiple locations around the world to monitor your service.To change regions for your monitors: _Select a monitor → Settings → Scheduling & Regions_.@@ -68,4 +68,4 @@ Oceania## Private Locations-You can also use private locations to monitor your services. Private locations are servers that you own and manage. If you want to use private locations, please [contact us](mailto:[email protected]) for more information.\ No newline at end of file+You can also use private locations to monitor your services. Private locations are servers that you own and manage. If you want to use private locations, you can learn how to set them up in our [How to create a private location (beta)](/tutorial/how-to-create-private-location) guide.diff --git a/apps/docs/src/content/docs/monitoring/customization/notification.mdx b/apps/docs/src/content/docs/monitoring/customization/notification.mdxindex 5cf94517f..14f2a715b 100644--- a/apps/docs/src/content/docs/monitoring/customization/notification.mdx+++ b/apps/docs/src/content/docs/monitoring/customization/notification.mdx@@ -1,6 +1,6 @@---title: Notifications-description: "How to set up notifications for your synthetic checks in OpenStatus"+description: "How to set up notifications for your synthetic checks in openstatus"---import { Image } from 'astro:assets';import { Aside} from '@astrojs/starlight/components';diff --git a/apps/docs/src/content/docs/monitoring/customization/timing.mdx b/apps/docs/src/content/docs/monitoring/customization/timing.mdxindex 7a4f3ee1e..c35d5c7e8 100644--- a/apps/docs/src/content/docs/monitoring/customization/timing.mdx+++ b/apps/docs/src/content/docs/monitoring/customization/timing.mdx@@ -1,9 +1,9 @@---title: Timing-description: "How to set up timing threshold for your synthetic checks in OpenStatus"+description: "How to set up timing threshold for your synthetic checks in openstatus"----By default, OpenStatus will timeout after `45s` but you can set a custom timeout (max. `45s`).+By default, openstatus will timeout after `45s` but you can set a custom timeout (max. `45s`).You can also set a custom degraded threshold. If the response time is higher than the degraded threshold, the status will be set to `Degraded` and we will send a notification.diff --git a/apps/docs/src/content/docs/monitoring/group-monitor-tag.mdx b/apps/docs/src/content/docs/monitoring/group-monitor-tag.mdxindex 7019fcfc7..5f7e4075b 100644--- a/apps/docs/src/content/docs/monitoring/group-monitor-tag.mdx+++ b/apps/docs/src/content/docs/monitoring/group-monitor-tag.mdx@@ -1,6 +1,6 @@---title: How to group your monitors-description: "How to group your monitors in OpenStatus to manage them more efficiently"+description: "How to group your monitors in openstatus to manage them more efficiently"---import { Image } from 'astro:assets';@@ -16,7 +16,7 @@ You can create a tag by going to settings tab of your monitor and adding a new t<Imagesrc={createTag}- alt="OpenStatus create monitor tag"+ alt="openstatus create monitor tag"/>@@ -26,5 +26,5 @@ Once you have created tags, you can filter your monitors by tags. This helps you<Imagesrc={filterTag}- alt="OpenStatus filter by tag"+ alt="openstatus filter by tag"/>diff --git a/apps/docs/src/content/docs/monitoring/monitor-data-collected.mdx b/apps/docs/src/content/docs/monitoring/monitor-data-collected.mdxindex 919a067e2..43113ba4f 100644--- a/apps/docs/src/content/docs/monitoring/monitor-data-collected.mdx+++ b/apps/docs/src/content/docs/monitoring/monitor-data-collected.mdx@@ -1,6 +1,6 @@---title: Monitor Data Points-description: "Monitor metrics are the data points that are collected by the monitor during the check in OpenStatus."+description: "Monitor metrics are the data points that are collected by the monitor during the check in openstatus."---import { Image } from 'astro:assets';@@ -18,7 +18,7 @@ To view your monitor data points, navigate to the monitor details page and click<Imagesrc={ResponseLog}- alt="OpenStatus response log"+ alt="openstatus response log"/>@@ -33,7 +33,7 @@ These are the data points that are collected by the monitor during the check.<Imagesrc={ResponseLogHeader}- alt="OpenStatus response log"+ alt="openstatus response log"/>@@ -52,11 +52,11 @@ For an HTTP monitor, the following metrics are collected:<Imagesrc={ResponseLogTiming}- alt="OpenStatus response log timing"+ alt="openstatus response log timing"/>### TCP Monitor MetricsFor a TCP monitor, the following metrics are collected:- **Response Time**: The time taken by the server to respond to the request.-- **TCP timing**: The time taken to establish a TCP connection.\ No newline at end of file+- **TCP timing**: The time taken to establish a TCP connection.diff --git a/apps/docs/src/content/docs/monitoring/monitoring-as-code.mdx b/apps/docs/src/content/docs/monitoring/monitoring-as-code.mdxindex 532b91086..08fdda86a 100644--- a/apps/docs/src/content/docs/monitoring/monitoring-as-code.mdx+++ b/apps/docs/src/content/docs/monitoring/monitoring-as-code.mdx@@ -1,6 +1,6 @@---title: Monitoring as Code-description: "How to manage monitors as code with OpenStatus?"+description: "How to manage monitors as code with openstatus?"---## Introduction@@ -14,7 +14,7 @@ Monitoring as code is a practice that allows you to define and manage your monit## Getting Started-OpenStatus provides a [CLI](/tutorial/get-started-with-openstatus-cli) tool that allows you to create, update, and delete monitors as code. To get started, you need to install the CLI tool.+openstatus provides a [CLI](/tutorial/get-started-with-openstatus-cli) tool that allows you to create, update, and delete monitors as code. To get started, you need to install the CLI tool.## Examples@@ -39,7 +39,7 @@ uptime-monitor:url: https://openstat.usmethod: GETheaders:- User-Agent: OpenStatus+ User-Agent: openstatusassertions:- kind: statusCodecompare: eq@@ -69,7 +69,7 @@ mcp-server:"method": "ping"}headers:- User-Agent: OpenStatus+ User-Agent: openstatusAccept: application/json, text/event-streamContent-Type: application/jsonassertions:@@ -81,4 +81,4 @@ mcp-server:target: '{"result":{},"jsonrpc":"2.0","id":"openstatus"}'```-You can find more examples in the [OpenStatus Template GitHub repository](https://github.com/openstatusHQ/cli-template/).+You can find more examples in the [openstatus Template GitHub repository](https://github.com/openstatusHQ/cli-template/).diff --git a/apps/docs/src/content/docs/monitoring/opentelemetry.mdx b/apps/docs/src/content/docs/monitoring/opentelemetry.mdxindex 45d2971dd..fcff74ff0 100644--- a/apps/docs/src/content/docs/monitoring/opentelemetry.mdx+++ b/apps/docs/src/content/docs/monitoring/opentelemetry.mdx@@ -1,6 +1,6 @@---title: OpenTelemetry-description: "How to export your synthetic monitoring data to your observability platform with OpenStatus"+description: "How to export your synthetic monitoring data to your observability platform with openstatus"---import { Aside } from '@astrojs/starlight/components';@@ -10,10 +10,10 @@ import { Aside } from '@astrojs/starlight/components';-## How to export your synthetic monitoring data to your observability stack with OpenStatus+## How to export your synthetic monitoring data to your observability stack with openstatus-OpenStatus supports exporting your synthetic monitoring data to your observability platform using OpenTelemetry.+openstatus supports exporting your synthetic monitoring data to your observability platform using OpenTelemetry.When you enable this feature, we will export the results of the synthetic checks as metrics.@@ -28,7 +28,7 @@ You can send your metrics to:#### Grafana Cloud Example-[OpenStatus X Grafana Public dashboard](https://openstatus.grafana.net/public-dashboards/a85806536e9243f7ab9e0d458eb2ad32)+[openstatus X Grafana Public dashboard](https://openstatus.grafana.net/public-dashboards/a85806536e9243f7ab9e0d458eb2ad32)### How to setup?diff --git a/apps/docs/src/content/docs/monitoring/overview.mdx b/apps/docs/src/content/docs/monitoring/overview.mdxindex f6e58a214..b7ba5fb77 100644--- a/apps/docs/src/content/docs/monitoring/overview.mdx+++ b/apps/docs/src/content/docs/monitoring/overview.mdx@@ -1,17 +1,25 @@----title: Overview-description: "Learn more about synthetic monitoring and how to use it with OpenStatus"+title: Monitoring Overview+description: "Introduction to synthetic monitoring with openstatus"---import { CardGrid, LinkCard } from '@astrojs/starlight/components';import { Image } from 'astro:assets';import overview from '../../../assets/monitor/overview/dashboard.png';+## What is synthetic monitoring?+With openstatus, you can simulate user requests to check the availability and performance of your website, API, or server from different locations around the globe. This proactive approach helps you find issues before your users do.+Synthetic monitoring complements real user monitoring (RUM) by providing:+- **Consistent baseline**: Predictable checks at regular intervals+- **Early warning system**: Detect issues before they affect many users+- **Global perspective**: Monitor from multiple regions simultaneously+- **24/7 coverage**: Continuous monitoring, even when you have no traffic+<Imagesrc={overview}- alt="Charts with status code and response time"+ alt="openstatus dashboard showing status codes and response time charts"/>@@ -36,13 +44,31 @@ You can create a new monitor in one of four ways:### Monitor types+We support different types of monitors for various use cases:+<CardGrid><LinkCardtitle="HTTP Monitor"href="/monitoring/type/http"+ description="Monitor HTTP/HTTPS endpoints including APIs and websites"/><LinkCardtitle="TCP Monitor"href="/monitoring/type/tcp"+ description="Monitor TCP port availability for databases and services"/></CardGrid>++## Getting started++Ready to start monitoring? Follow these guides:++1. **[Create Your First Monitor](/tutorial/how-to-create-monitor)** - Step-by-step tutorial+2. **[Configure Notifications](/monitoring/customization/notification)** - Get alerted on issues+3. **[Set Up Assertions](/monitoring/customization/assertions)** - Validate response content++## Learn more++- **[Understanding Uptime Monitoring](/concept/uptime-monitoring)** - Core concepts explained+- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - What metrics we track+- **[Monitoring as Code](/monitoring/monitoring-as-code)** - Manage monitors with YAMLdiff --git a/apps/docs/src/content/docs/monitoring/type/http.mdx b/apps/docs/src/content/docs/monitoring/type/http.mdxindex f1ba9bddf..24ddcad90 100644--- a/apps/docs/src/content/docs/monitoring/type/http.mdx+++ b/apps/docs/src/content/docs/monitoring/type/http.mdx@@ -1,6 +1,6 @@---title: HTTP-description: "How to monitor your HTTP services with OpenStatus"+description: "How to monitor your HTTP services with openstatus"---import { Image } from 'astro:assets';@@ -35,4 +35,4 @@ If you need to set custom headers for your HTTP requests, you can do so by goingWhen you select the `POST` method, you can add a body payload to your request. This is useful when you need to send data to your service.-Payloads are often JSON or XML, but we also support plain text or binary files.\ No newline at end of file+Payloads are often JSON or XML, but we also support plain text or binary files.diff --git a/apps/docs/src/content/docs/monitoring/type/tcp.mdx b/apps/docs/src/content/docs/monitoring/type/tcp.mdxindex 4aa15bfcc..6aae63cbc 100644--- a/apps/docs/src/content/docs/monitoring/type/tcp.mdx+++ b/apps/docs/src/content/docs/monitoring/type/tcp.mdx@@ -1,6 +1,6 @@---title: TCP-description: "How to monitor your TCP services with OpenStatus"+description: "How to monitor your TCP services with openstatus"---import { Image } from 'astro:assets';@@ -15,4 +15,4 @@ import TCPMonitor from '../../../../assets/monitor/tcp-monitor.png';### URI (Host:Port)-Provide your Host and Port to monitor your TCP service. Could be a domain or IPv4/IPv6 address.\ No newline at end of file+Provide your Host and Port to monitor your TCP service. Could be a domain or IPv4/IPv6 address.diff --git a/apps/docs/src/content/docs/reference.mdx b/apps/docs/src/content/docs/reference.mdxindex f391f5758..6800e8cbd 100644--- a/apps/docs/src/content/docs/reference.mdx+++ b/apps/docs/src/content/docs/reference.mdx@@ -1,4 +1,57 @@----title: About this project-description: Learn more about the project I’m working on.+title: Reference Documentation+description: Technical specifications, API documentation, and configuration references---++import { CardGrid, LinkCard } from '@astrojs/starlight/components';++## 📖 Reference++Reference documentation provides **technical specifications** and detailed information about openstatus components, APIs, and configuration options. This is where you look up exact parameter names, return types, and available options.++### When to use reference docs++Reference documentation is ideal when you:+- Need to look up specific API endpoints or parameters+- Want to know all available configuration options+- Are looking for technical specifications+- Need to understand data structures and types++### Monitor Types++Detailed specifications for each monitor type:++<CardGrid>+ <LinkCard title="HTTP Monitor" href="/reference/http-monitor" description="Complete reference for HTTP/HTTPS endpoint monitoring" />+ <LinkCard title="TCP Monitor" href="/reference/tcp-monitor" description="TCP port monitoring specifications" />+ <LinkCard title="DNS Monitor" href="/reference/dns-monitor" description="DNS resolution monitoring reference" />+</CardGrid>++### Components & Features++<CardGrid>+ <LinkCard title="Status Page" href="/reference/status-page" description="Status page configuration options" />+ <LinkCard title="Status Report" href="/reference/status-report" description="Status report specifications" />+ <LinkCard title="Subscriber" href="/reference/subscriber" description="Status page subscriber reference" />+ <LinkCard title="Incident" href="/reference/incident" description="Incident management reference" />+ <LinkCard title="Notification" href="/reference/notification" description="Notification channel specifications" />+</CardGrid>++### Infrastructure & Tools++<CardGrid>+ <LinkCard title="CLI Reference" href="/reference/cli-reference" description="Complete command-line interface documentation" />+ <LinkCard title="Terraform Provider" href="/reference/terraform" description="Infrastructure as code with Terraform" />+ <LinkCard title="Private Location" href="/reference/private-location" description="Self-hosted monitoring agent reference" />+</CardGrid>++### API Documentation++For programmatic access to openstatus:+- **[REST API](https://api.openstatus.dev/v1)** - Full REST API reference with interactive examples++### Related sections++- **[Tutorials](/tutorial/getting-started/)** - Learn how to use these features step-by-step+- **[How-to guides](/guides/getting-started/)** - Practical examples of common use cases+- **[Explanations](/concept/getting-started/)** - Understand the concepts behind the reference materialdiff --git a/apps/docs/src/content/docs/reference/cli-reference.mdx b/apps/docs/src/content/docs/reference/cli-reference.mdxindex 469b521a5..f20e24d9e 100644--- a/apps/docs/src/content/docs/reference/cli-reference.mdx+++ b/apps/docs/src/content/docs/reference/cli-reference.mdx@@ -4,9 +4,9 @@ title: CLI Reference## CLI interface - openstatus-OpenStatus is a command line interface for managing your monitors and triggering your synthetics tests.+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.+This is openstatus Command Line Interface, the openstatus.dev CLI.Usage:@@ -30,7 +30,7 @@ Create or update monitors.> openstatus monitors apply [options]-Creates or updates monitors according to the OpenStatus configuration file.+Creates or updates monitors according to the openstatus configuration file.Usage:@@ -43,7 +43,7 @@ The following flags are supported:| Name | Description | Default value | Environment variables ||-----------------------------|-------------------------------------------------------|:-----------------:|:----------------------:|| `--config="…"` (`-c`) | The configuration file containing monitor information | `openstatus.yaml` | *none* |-| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` || `--auto-accept` (`-y`) | Automatically accept the prompt | `false` | *none* |@@ -65,7 +65,7 @@ The following flags are supported:| Name | Description | Default value | Environment variables ||-----------------------------|-----------------------------|:-----------------:|:----------------------:|-| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` || `--output="…"` (`-o`) | The output file name | `openstatus.yaml` | *none* |### `monitors info` subcommand@@ -86,7 +86,7 @@ The following flags are supported:| Name | Description | Default value | Environment variables ||-----------------------------|-----------------------------|:-------------:|:----------------------:|-| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |### `monitors list` subcommand@@ -107,7 +107,7 @@ The following flags are supported:| Name | Description | Default value | Environment variables ||-----------------------------|-------------------------------------------|:-------------:|:----------------------:|| `--all` | List all monitors including inactive ones | `false` | *none* |-| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |### `monitors trigger` subcommand@@ -127,7 +127,7 @@ The following flags are supported:| Name | Description | Default value | Environment variables ||-----------------------------|-----------------------------|:-------------:|:----------------------:|-| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |### `run` command (aliases: `r`)@@ -148,7 +148,7 @@ 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` |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |### `whoami` command (aliases: `w`)@@ -168,4 +168,4 @@ The following flags are supported:| Name | Description | Default value | Environment variables ||-----------------------------|-----------------------------|:-------------:|:----------------------:|-| `--access-token="…"` (`-t`) | OpenStatus API Access Token | | `OPENSTATUS_API_TOKEN` |+| `--access-token="…"` (`-t`) | openstatus API Access Token | | `OPENSTATUS_API_TOKEN` |diff --git a/apps/docs/src/content/docs/reference/dns-monitor.mdx b/apps/docs/src/content/docs/reference/dns-monitor.mdxindex a28505be2..bc685ff0c 100644--- a/apps/docs/src/content/docs/reference/dns-monitor.mdx+++ b/apps/docs/src/content/docs/reference/dns-monitor.mdx@@ -1,22 +1,133 @@----title: DNS Monitor+title: DNS Monitor Reference+description: Complete technical specification for DNS record monitoring----A DNS Monitor is a component that allows you to monitor the status of DNS records. It can be used to monitor the status of a domain name, a subdomain, or any other DNS record.+## Overview-It will fetch the following DNS record types:-- A-- AAAA-- CNAME-- MX-- NS-- TXT+A DNS Monitor is a component designed to verify the availability and correctness of DNS records. It performs periodic lookups for specified DNS record types against a target domain or subdomain from various geographical locations.++**Use cases:**+- Validating domain name resolution+- Monitoring changes to critical DNS records (e.g., A, CNAME, MX)+- Ensuring proper load balancing via DNS (when combined with multi-region checks)+- Detecting unauthorized DNS alterations## Configuration-### URI-The domain or subdomain you want to monitor e.g `openstat.us`+### URI++**Type:** String (required)+**Format:** Domain name or subdomain++The fully qualified domain name or subdomain to be monitored.++**Examples:**+- `openstat.us`+- `api.example.com`+- `mail.example.org`++### Record Types++The monitor supports fetching and validating the following DNS record types:++- `A` (Address Record): Maps a domain name to an IPv4 address.+- `AAAA` (IPv6 Address Record): Maps a domain name to an IPv6 address.+- `CNAME` (Canonical Name Record): Maps an alias domain name to another canonical domain name.+- `MX` (Mail Exchange Record): Specifies the mail servers responsible for accepting email messages on behalf of a domain name.+- `NS` (Name Server Record): Delegates a domain or subdomain to a set of authoritative name servers.+- `TXT` (Text Record): Carries arbitrary human-readable text and is also used for various purposes like SPF, DKIM, DMARC, and site verification.++### Regions++The geographical locations from which the DNS monitoring checks are performed. This allows for verification of DNS propagation and performance across different networks.++__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 interval at which the DNS checks are performed. Supported frequencies:+- 30 seconds+- 1 minute+- 5 minutes+- 10 minutes+- 30 minutes+- 1 hour++### Response Time Thresholds++#### Timeout++**Type:** Duration (optional)+**Default:** `45 seconds`++The maximum duration to wait for a DNS response. If the lookup exceeds this time, the check is considered failed.++#### Degraded++**Type:** Duration (optional)++The duration after which a DNS response is considered degraded. This indicates a performance issue without being a complete failure.++### Retry++**Type:** Integer (optional)+**Default:** `3`++The number of times the monitor will retry a failed DNS lookup before reporting a definitive failure. For example: `3`-### Regions+## Related resources-The regions where we are triggering the DNS request.+- **[Monitoring Overview](/monitoring/overview)** - Conceptual overview of monitoring within OpenStatus.+- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - Details on all metrics collected by monitors.+- **[CLI Reference](/reference/cli-reference)** - Manage monitors as code using the OpenStatus CLI.diff --git a/apps/docs/src/content/docs/reference/http-monitor.mdx b/apps/docs/src/content/docs/reference/http-monitor.mdxindex d397b0956..7fad568fc 100644--- a/apps/docs/src/content/docs/reference/http-monitor.mdx+++ b/apps/docs/src/content/docs/reference/http-monitor.mdx@@ -1,44 +1,103 @@----title: HTTP Monitor+title: HTTP Monitor Reference+description: Complete technical specification for HTTP/HTTPS endpoint monitoring----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.+## Overview++An HTTP Monitor is a component that allows you to monitor the status of HTTP and HTTPS endpoints. It can be used to monitor websites, APIs, webhooks, or any other HTTP-accessible service.++**Use cases:**+- Website uptime monitoring+- API health checks+- Webhook endpoint validation+- CDN performance monitoring+- Authentication endpoint testing## Configuration### URL-The url of the HTTP endpoint you want to monitor e.g `https://openstat.us`+**Type:** String (required)+**Format:** Full URL including protocol++The URL of the HTTP endpoint you want to monitor.++**Examples:**+- `https://openstat.us`+- `https://api.example.com/health`+- `http://internal-service.local:8080/status`++**Note:** We recommend using HTTPS for better security.### Methods-The HTTP method you want to use to monitor the endpoint.-- `GET`-- `POST`-- `PUT`-- `DELETE`-- `HEAD`-- `OPTIONS`-- `PATCH`-- `TRACE`+**Type:** String (required)+**Default:** `GET`++The HTTP method to use when making the request to the endpoint.++**Available methods:**+- `GET` - Retrieve data (most common for health checks)+- `POST` - Send data to create/trigger actions+- `PUT` - Update existing resources+- `DELETE` - Remove resources+- `HEAD` - Like GET but without response body+- `OPTIONS` - Query supported methods+- `PATCH` - Partial resource updates+- `TRACE` - Echo request for debugging++**Common usage:**+- Health checks: `GET`+- API testing: `POST`, `PUT`, `DELETE`+- Webhook testing: `POST`### 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...`+**Type:** String (optional)+**Available for:** `POST`, `PUT`, `PATCH` methods++The request body to send with the HTTP request. Supports both text and binary data.++**Text body examples:**+```json+{ "key": "value" }+```++**Binary data:**+For binary content (e.g., images), use base64 encoding with data URI:+```+data:image/jpeg;base64,/9j...+```++**Content type:** Set the appropriate `Content-Type` header (e.g., `application/json`, `application/octet-stream`).### Headers-The headers you want to send with the HTTP request+**Type:** Key-value pairs (optional)++Custom HTTP headers to include with your request.-Example:-- `"Content-Type": "application/json"`-- `'Content-Type: application/octet-stream'`+**Common examples:**+```+Content-Type: application/json+Authorization: Bearer your_token_here+Accept: application/json+User-Agent: Custom-Agent/1.0+```++**Use cases:**+- **Authentication:** Send API tokens or credentials+- **Content negotiation:** Specify accepted response formats+- **Custom identification:** Add tracking or debugging headers++**Note:** openstatus automatically adds `User-Agent: openstatus/1.0` to all requests.### Regions-The regions where we are triggering the HTTP request.+**Type:** Array of Strings (required)+**Format:** Region identifiers (e.g., `iad`, `jnb`)++The geographical regions from which the HTTP request will be triggered. This allows for monitoring global availability and performance.__Africa__@@ -94,54 +153,126 @@ __Oceania__### Frequency-The check interval, we support the following frequencies:-- 30 seconds-- 1 minute-- 5 minutes-- 10 minutes-- 30 minutes-- 1 hour+**Type:** String (required)+**Format:** Duration string (e.g., `30s`, `1m`, `1h`)++The interval at which the HTTP monitor will perform checks. Supported 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`++**Type:** Duration (optional)+**Default:** `45 seconds`++The maximum duration to wait for the HTTP request to complete. If the request exceeds this time, it is considered a failure.+#### Degraded-The duration for which the HTTP request is considered degraded.++**Type:** Duration (optional)++The duration after which the HTTP request is considered to be performing in a degraded state. This threshold allows for proactive alerting on performance issues before a complete outage.### Retry-The number of retries for the HTTP request. For example: `3`++**Type:** Integer (optional)+**Default:** `3`++The number of times the monitor will automatically retry the HTTP request upon failure before reporting a definitive error. 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++Assertions allow you to validate specific aspects of the HTTP response.++#### Body Assertions++Validate the content of the HTTP response body.++**Comparisons:**+- `Contains`: The response body must include the specified string.+- `Not Contains`: The response body must not include the specified string.+- `Equal`: The response body must exactly match the specified string.+- `Not Equal`: The response body must not exactly match the specified string.+- `Empty`: The response body must be empty.++#### Status Code Assertions++Validate the HTTP status code of the response.++**Comparisons:**+- `Equal`: The status code must be exactly the specified value.+- `Not Equal`: The status code must not be the specified value.+- `Greater Than`: The status code must be greater than the specified value.+- `Greater Than or Equal`: The status code must be greater than or equal to the specified value.+- `Less Than`: The status code must be less than the specified value.+- `Less Than or Equal`: The status code must be less than or equal to the specified value.++#### Headers Assertions++Validate the presence or content of specific HTTP response headers.++**Purpose:** Verify cache headers, check security headers (e.g., `X-Frame-Options`), validate content-type.++**Comparisons:**+- `Contains`: A header's value must include the specified string.+- `Not Contains`: A header's value must not include the specified string.+- `Equal`: A header's value must exactly match the specified string.+- `Not Equal`: A header's value must not exactly match the specified string.+- `Empty`: A header's value must be empty or the header must not be present.++**Example Use Cases:**+- Verify `Cache-Control` headers are present and correct.+- Check for the existence of security-related headers like `Strict-Transport-Security`.+- Validate the `Content-Type` header in API responses.### OpenTelemetry++Configures the export of monitoring metrics to an OpenTelemetry-compatible observability platform.+#### OTLP Endpoint-The endpoint we use to export the metrics. We only support HTTP endpoint.++**Type:** String (optional)+**Protocol:** HTTP only++The OTLP (OpenTelemetry Protocol) endpoint URL where collected metrics should be exported.++**Example:** `https://otlp.example.com/v1/metrics`+#### OTLP Headers-The headers we use to export the metrics to your otlp endpoint.++**Type:** Key-value pairs (optional)++Custom headers to include when sending metrics to your OTLP endpoint. Commonly used for authentication or tenant identification.++**Common example:**+```+Authorization: Bearer <your_token>+```### Public-If set to true the monitors data is accessible on the status page (default:`false`)++**Type:** Boolean+**Default:** `false`++Controls the visibility of monitor data on your public status page.++- `true`: Monitor metrics and status are visible to all visitors of your status page.+- `false`: Monitor data remains private, accessible only within your OpenStatus dashboard.++**Use cases for public visibility:**+- Enhancing transparency with users regarding service health.+- Providing public API status pages.+- Displaying SaaS service availability to customers.++## Related resources++- **[Create Your First Monitor](/tutorial/how-to-create-monitor)** - Step-by-step tutorial on setting up a monitor.+- **[Monitoring Overview](/monitoring/overview)** - Conceptual overview of OpenStatus monitoring capabilities.+- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - Detailed information on all metrics and data points collected by monitors.+- **[CLI Reference](/reference/cli-reference)** - Guide to managing OpenStatus monitors programmatically using the command-line interface.diff --git a/apps/docs/src/content/docs/reference/incident.mdx b/apps/docs/src/content/docs/reference/incident.mdxindex 2849787e3..cebe7b5b6 100644--- a/apps/docs/src/content/docs/reference/incident.mdx+++ b/apps/docs/src/content/docs/reference/incident.mdx@@ -1,7 +1,45 @@----title: Incident+title: Incident Reference+description: Technical specification for incident management and lifecycle----An incident is a problem related to a monitor. They are created automatically when a monitor fails.+## Overview-At least 50% must have failed to trigger the incident.+An incident in OpenStatus represents a detected problem or service disruption related to a monitored resource. Incidents are automatically generated when a monitor reports a failure condition that meets predefined criteria. They serve as a central point for tracking, managing, and resolving service impairments.++**Key characteristics:**+- Automatically triggered by monitor failures.+- Aggregates related failure events for a single monitor.+- Provides a clear status of service health.++## Incident Triggering++An incident is triggered when a significant percentage of recent monitoring checks for a given monitor report a failed status. This mechanism prevents false positives from transient network issues.++**Trigger Condition:**+- **Failure Threshold:** An incident is initiated when at least 50% of the checks within a defined window (e.g., the last `N` checks or within a `T` duration) have reported a `failure` or `degraded` status.++## Incident Lifecycle and States++Incidents progress through several states reflecting their current resolution status. These states are managed through status reports (see [Status Report Reference](/reference/status-report)).++**Primary States:**+- `investigating`: The incident has been detected, and the team is actively looking into the root cause.+- `identified`: The root cause of the incident has been identified.+- `monitoring`: A fix has been deployed or a mitigation is in place, and the service is being monitored to confirm resolution.+- `resolved`: The incident has been fully resolved, and the service is operating normally.++## Properties++While an incident is active, it collects and displays key information related to the service disruption.++- **Monitor Association:** Each incident is directly linked to the monitor that triggered it, providing immediate context to the affected service.+- **Start Time:** Timestamp indicating when the incident was first detected and created.+- **Status Reports:** A chronological log of all updates and state changes applied to the incident.+- **Impacted Locations:** Details on the geographical regions from which the monitor reported failures.++## Related resources++- **[Status Report Reference](/reference/status-report)** - Details on how incident statuses are managed and reported.+- **[Monitoring Overview](/monitoring/overview)** - Conceptual overview of monitoring within OpenStatus.+- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - All tracked metrics collected by monitors.diff --git a/apps/docs/src/content/docs/reference/notification.mdx b/apps/docs/src/content/docs/reference/notification.mdxindex 06d588c75..0a596e7c9 100644--- a/apps/docs/src/content/docs/reference/notification.mdx+++ b/apps/docs/src/content/docs/reference/notification.mdx@@ -1,55 +1,85 @@----title: Notification+title: Notification Channels Reference+description: Technical specification for OpenStatus notification channels and alert payloads.----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.+## Overview+Notifications in OpenStatus provide real-time alerts regarding changes in monitor status, such as recovery from an outage or detection of a new failure. By default, no notification channels are configured in a new workspace. Users must configure and enable specific channels to receive alerts.-## Notification Channels:+## Notification Channels++Each notification channel requires specific configuration parameters to enable alert delivery.### Slack-Require a [Slack incoming webhook](https://api.slack.com/incoming-webhooks)+Integrates with Slack to send alerts to a designated channel.++**Configuration:**+- **Incoming Webhook URL:** (Required) A [Slack incoming webhook URL](https://api.slack.com/incoming-webhooks) where notifications will be posted.-Require an email address+Sends alerts directly to a specified email address.++**Configuration:**+- **Email Address:** (Required) The recipient's 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`+Delivers alerts to a Discord channel via a webhook.++**Configuration:**+- **Webhook URL:** (Required) A [Discord webhook URL](https://support.discord.com/hc/en-us/articles/228383668) for the target channel.+ **Example:** `https://discordapp.com/api/webhooks/123456789012345678/abcdefghijklmnopqrstuvwxyz1234567890`### Google Chat-Require a [Google Chat webhook](https://developers.google.com/workspace/chat/quickstart/webhooks)+Sends notifications to a Google Chat space.++**Configuration:**+- **Webhook URL:** (Required) A [Google Chat webhook URL](https://developers.google.com/workspace/chat/quickstart/webhooks) for the target space.+### SMS-Require a phone number (international format e.g. +14155552671)+Sends alerts as SMS messages to a mobile phone number.++**Configuration:**+- **Phone Number:** (Required) The recipient's phone number in international format (e.g., `+14155552671`).-Due to provider routing, SMS may not be delivered to all countries. Please contact support if you encounter any issues. Or use whatsapp notification instead.+**Note:** SMS delivery can vary by country due to provider routing. Contact support if delivery issues are encountered. WhatsApp notifications may be an alternative.-Require a phone number (international format e.g. +14155552671)+Sends alerts as WhatsApp messages to a mobile phone number.+**Configuration:**+- **Phone Number:** (Required) The recipient's phone number in international format (e.g., `+14155552671`).### Telegram-Requires to know the chat id.+Delivers alerts to a specified Telegram chat.-> This integration is fully functional but accessing the chat id is not smooth yet. It requires manual effort to access your chat id. **You can ask RawDataBot `@raw_info_bot` for your chat id.**+**Configuration:**+- **Chat ID:** (Required) The unique identifier for the Telegram chat. This typically requires manual retrieval; users can ask `@raw_info_bot` for their chat ID.-The bot's id is `@openstatushq_bot` to make sure you are getting the correct notifications.+**Bot ID:** The official OpenStatus Telegram bot ID is `@openstatushq_bot`.### Webhook-- URL (require)-- Headers (optional)+Sends HTTP POST requests to a custom endpoint with a JSON payload.++**Configuration:**+- **URL:** (Required) The endpoint URL to which the webhook payload will be sent.+- **Headers:** (Optional) Custom HTTP headers to include with the webhook request (key-value pairs).#### Notification Payloads-##### Payload for Monitor Recovery+Webhook notifications utilize specific JSON payloads for different monitor status changes.++##### Monitor Recovery Payload++Sent when a monitor recovers from a `degraded` or `error` state.```json{@@ -65,19 +95,21 @@ The bot's id is `@openstatushq_bot` to make sure you are getting the correct not}```+**Payload Fields:**-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.+| Field | Type | Description |+| :------------ | :------- | :------------------------------------------------------------------- |+| `monitor.id` | `number` | Unique identifier of the monitor. |+| `monitor.name`| `string` | Name of the monitor. |+| `monitor.url` | `string` | The URL or URI being monitored. |+| `cronTimestamp`| `number` | Timestamp of the check execution in milliseconds since epoch. |+| `status` | `string` | Indicates the monitor status: `"recovered"`. |+| `statusCode` | `number` | (Optional) HTTP status code returned by the monitored service. |+| `latency` | `number` | (Optional) Time taken to complete the check in milliseconds. |+##### Monitor Failure Payload-##### Payload for Monitor Failure+Sent when a monitor enters an `error` or `degraded` state.```json{@@ -92,19 +124,20 @@ Fields Explanation:}```-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.+**Payload Fields:**+| Field | Type | Description |+| :------------ | :------- | :------------------------------------------------------------------- |+| `monitor.id` | `number` | Unique identifier of the monitor. |+| `monitor.name`| `string` | Name of the monitor. |+| `monitor.url` | `string` | The URL or URI being monitored. |+| `cronTimestamp`| `number` | Timestamp of the check execution in milliseconds since epoch. |+| `status` | `string` | Indicates the monitor status: `"degraded"` or `"error"`. |+| `errorMessage`| `string` | (Optional) A description of the error encountered during the check. |#### Zod Schema+The validation schema for webhook payloads:```tsimport { z } from "zod";@@ -121,18 +154,32 @@ export const PayloadSchema = z.object({latency: z.number().optional(),errorMessage: z.string().optional(),});-````+```### OpsGenie-- API key from OpsGenie (required)+Integrates with OpsGenie for incident management.++**Configuration:**+- **API Key:** (Required) An API key obtained from your OpsGenie account.### PagerDuty-Follow the step in PagerDuty workflow+Integrates with PagerDuty for incident alerting.++**Configuration:**+- **Integration Steps:** (Required) Follow the specific integration steps provided within the PagerDuty workflow to set up this channel.### Ntfy-- Ntfy topic (required)-- Custom server url (optional)-- bearer token (optional)+Sends notifications to an Ntfy topic.++**Configuration:**+- **Ntfy Topic:** (Required) The topic name to which notifications will be published.+- **Custom Server URL:** (Optional) The URL of a custom Ntfy server if not using the default.+- **Bearer Token:** (Optional) An authentication token for accessing the Ntfy server.++## Related resources++- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - Details on all metrics collected by monitors.+- **[Incident Reference](/reference/incident)** - Information about incident creation and management.diff --git a/apps/docs/src/content/docs/reference/private-location.mdx b/apps/docs/src/content/docs/reference/private-location.mdxindex dbf211167..5e84bc935 100644--- a/apps/docs/src/content/docs/reference/private-location.mdx+++ b/apps/docs/src/content/docs/reference/private-location.mdx@@ -1,7 +1,43 @@----title: Private Location+title: Private Location Reference+description: Technical specification for configuring and utilizing private monitoring locations.----A private location is a location that you can set up within your own infrastructure to run monitoring checks from there.+## Overview-For example this is useful if you want to monitor services that are not publicly accessible, such as internal APIs or services behind a firewall.+A private location in OpenStatus enables users to deploy monitoring probes within their own infrastructure or private networks. This capability is essential for monitoring internal services, APIs, or systems that are not publicly accessible from the internet, such as those behind firewalls or within a Virtual Private Cloud (VPC).++**Key benefits:**+- **Internal Monitoring:** Monitor services running on private networks.+- **Security:** Keep sensitive internal endpoints protected from public exposure.+- **Compliance:** Meet specific regulatory or security compliance requirements by controlling data paths.+- **Reduced Latency:** Conduct checks closer to your services for more accurate performance metrics.++## How it Works++When a private location is configured, OpenStatus provides a mechanism (e.g., a container image or agent) that you deploy within your private environment. This deployed component acts as a local monitoring probe, executing checks on behalf of your OpenStatus account.++1. **Deployment:** You deploy the OpenStatus private probe within your chosen infrastructure (e.g., a Docker container on a server, a Kubernetes pod).+2. **Secure Connection:** The private probe establishes a secure, outbound-only connection to the OpenStatus platform, eliminating the need for inbound firewall rules.+3. **Check Execution:** OpenStatus dispatches monitoring tasks to your private probe via this secure connection. The probe then executes the configured checks against your internal services.+4. **Result Reporting:** The private probe securely sends the monitoring results (e.g., status, latency, response data) back to the OpenStatus platform for processing, alerting, and visualization.++## Configuration++Detailed steps for setting up a private location involve:++1. **Probe Deployment:** Provisioning a server or container environment within your private network.+2. **Agent Installation:** Deploying the OpenStatus private probe agent (e.g., Docker image) onto your infrastructure.+3. **Authentication:** Configuring the probe with necessary API keys or tokens to securely authenticate with your OpenStatus workspace.+4. **Network Access:** Ensuring the deployed probe has network access to the internal services it needs to monitor, as well as outbound access to the OpenStatus platform.++**Example Use Cases:**+- Monitoring an internal REST API that is only accessible from within your corporate network.+- Checking the health of a database server running on a private subnet.+- Performing synthetic transactions on an internal web application before it's exposed publicly.++## Related resources++- **[How to Deploy Probes on Cloudflare Containers](/guides/how-to-deploy-probes-cloudflare-containers)** - A guide for deploying private probes using Cloudflare Workers/Containers. (Example deployment guide)+- **[Monitoring Overview](/monitoring/overview)** - Conceptual overview of monitoring within OpenStatus.+- **[CLI Reference](/reference/cli-reference)** - Manage monitors as code, including those utilizing private locations.diff --git a/apps/docs/src/content/docs/reference/status-page.mdx b/apps/docs/src/content/docs/reference/status-page.mdxindex 65b4fa48b..cf598a51f 100644--- a/apps/docs/src/content/docs/reference/status-page.mdx+++ b/apps/docs/src/content/docs/reference/status-page.mdx@@ -1,54 +1,87 @@----title: Status Page+title: Status Page Reference+description: Complete technical specification for OpenStatus status page configuration.----A status page is a web page that displays the current status of a service or system.+## Overview++A status page is a dedicated web interface provided by OpenStatus that publicly displays the operational status of your services and systems. It serves as a transparent communication tool during incidents and for showcasing overall service health.++**Key features:**+- Real-time service status updates.+- Incident communication and history.+- Customizable branding and domain.+- Multiple access control options.## Configuration+OpenStatus provides several configuration options to customize your status page's appearance, accessibility, and functionality.+### 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`+**Type:** String (required)+**Format:** URL-friendly string (e.g., `my-service-status`)++A unique identifier that forms part of your status page's default URL. For example, a slug of `status` will result in a URL like `https://status.openstatus.dev`.### Custom Domain-You can configure a custom domain for your status page. e.g `status.example.com` => `https://status.example.com`+**Type:** String (optional)+**Format:** Valid domain name (e.g., `status.example.com`)++Allows you to host your status page on a custom domain. Once configured, your status page will be accessible at `https://your-custom-domain.com`.++### Password (Basic Auth)-### Password (basic auth)+**Type:** String (optional)-You can add a password for your status page to protect a status page. If you are not authenticated, you will get redirected to the `/login`.+Enables basic password protection for your status page. If a password is set, users will be redirected to a login page (`/login`) to gain access. The password is stored in a cookie upon successful authentication.-The password is stored in plain text in a `cookie`, so keep the password easy and fun. You can share any page by appending the password via the `pw` search param like: `https://[slug].openstatus.dev/?pw=my-secret-password` and we will automatically authenticate the user. This can be useful to authenticate to private RSS feeds.+**Sharing with password:** You can provide direct access by appending the password as a URL search parameter: `https://[slug].openstatus.dev/?pw=your-secret-password`. This method is also useful for authenticating private RSS feeds.-### Magic Link (session auth)+### Magic Link (Session Auth)-You can secure your status page by restricting access to users with approved email domains. Users will receive a magic link sent to their email and, upon clicking it, will be authenticated via a session token.+**Type:** Boolean (add-on feature)-This feature is available as an add-on for paid plans and is not included by default.+Restricts access to your status page to users with approved email domains. Users receive a magic link via email, which, upon clicking, authenticates them via a session token. This feature is typically available as a paid add-on for specific plans.### Favicon-You can add a favicon for your status page.+**Type:** Image file (e.g., `.ico`, `.png`)+Allows you to upload a custom favicon that will appear in browser tabs and bookmarks for your status page.-### JSON Feed+### JSON Feed-You can access your status page data in JSON format by appending `/feed/json` to your status page URL.+**Type:** Read-only endpoint+**Format:** JSON-Example: `https://status.openstatus.dev/feed/json`+Provides a machine-readable JSON representation of your status page data. This feed can be accessed by appending `/feed/json` to your status page URL.++**Example:** `https://status.openstatus.dev/feed/json`### SSH Command-Check the current status page anytime from your Terminal with:+**Type:** Command-line utility-```+Allows you to quickly check the current status page status directly from your terminal using an SSH command.++**Usage:**++```bashssh [slug]@ssh.openstatus.dev```-Example: `ssh [email protected]`+**Example:** `ssh [email protected]`### White Label-The White Label add-on allows you to remove the "powered by openstatus.dev" footer from your status page, providing a fully branded experience for your users.+**Type:** Boolean (add-on feature)++Removes the "powered by openstatus.dev" footer from your status page, providing a fully branded experience. This feature is typically available as a paid add-on for Starter and Pro plans and is enabled via your workspace settings, affecting all status pages within that workspace.++## Related resources-This feature is available as a paid add-on for Starter and Pro plans at $300/month. Once enabled in your workspace settings, the OpenStatus branding will be removed from all status pages in your workspace.\ No newline at end of file+- **[Create Status Page](/status-page/create-status-page)** - Step-by-step tutorial on creating a status page.+- **[How to Configure Status Page](/tutorial/how-to-configure-status-page)** - Guide on advanced status page configuration.+- **[Status Report Reference](/reference/status-report)** - Details on how incident statuses are managed and reported.diff --git a/apps/docs/src/content/docs/reference/status-report.mdx b/apps/docs/src/content/docs/reference/status-report.mdxindex e2ee9344e..7a6f8f3a4 100644--- a/apps/docs/src/content/docs/reference/status-report.mdx+++ b/apps/docs/src/content/docs/reference/status-report.mdx@@ -1,25 +1,56 @@----title: Status Report+title: Status Report Reference+description: Technical specification for incident status updates within OpenStatus.----A status report is an event of an incident.+## Overview+A status report is a chronological update or event associated with an ongoing incident in OpenStatus. These reports are crucial for communicating the progress of an incident, from initial detection to final resolution, providing transparency to stakeholders.-## Configuration+**Purpose:**+- To document the lifecycle and progress of an incident.+- To communicate current incident status and actions taken.+- To provide historical context for post-incident analysis.++## Relationship to Incidents++Each status report is directly linked to a specific incident. As an incident progresses through its resolution process, new status reports are added to provide updates, often accompanied by a change in the incident's overall status.++## Configuration and Properties++A status report consists of several key properties that define its content and context.### Status-The status of an incident can be:+**Type:** Enumerated String (required)++Represents the current stage or state of the associated incident at the time the report is issued. The available statuses are:-- `investigating`-- `identified`-- `monitoring`-- `resolved`+- `investigating`: The incident has been detected, and the team is actively looking into the root cause.+- `identified`: The root cause of the incident has been identified.+- `monitoring`: A fix has been deployed or a mitigation is in place, and the service is being monitored to confirm resolution.+- `resolved`: The incident has been fully resolved, and the service is operating normally.### Date-The date of the status report+**Type:** Datetime (required)+**Format:** ISO 8601 (e.g., `2026-01-05T12:30:00Z`)++The timestamp indicating when the status report was created or when the reported status took effect. This provides a clear timeline for incident progression.### Message-The message of the status report+**Type:** String (required)++A descriptive message detailing the update, actions taken, or any relevant information regarding the incident at the time of the report. This message should be clear and concise, providing context to the status change.++**Example Messages:**+- `"Initial detection of elevated error rates on the API. Investigating potential upstream issues."`+- `"Root cause identified as a misconfigured caching layer. Working on a rollback."`+- `"Fix deployed to production. Monitoring service health for full recovery."`+- `"All services restored to normal operation. Incident resolved."`++## Related resources++- **[Incident Reference](/reference/incident)** - Detailed information on incident creation and lifecycle.+- **[Status Page Reference](/reference/status-page)** - Information on how status reports are displayed on public status pages.diff --git a/apps/docs/src/content/docs/reference/subscriber.mdx b/apps/docs/src/content/docs/reference/subscriber.mdxindex 4468ea642..62c31664d 100644--- a/apps/docs/src/content/docs/reference/subscriber.mdx+++ b/apps/docs/src/content/docs/reference/subscriber.mdx@@ -1,7 +1,43 @@----title: Subscriber+title: Subscriber Reference+description: Technical specification for managing status page subscribers and their notifications.----A subscriber is a user who receives notifications about incidents.+## Overview-They have to subscribe to update from your status page.+A subscriber in OpenStatus is an entity (typically a user or an integration) that opts to receive real-time notifications and updates regarding incidents and status changes on a specific status page. Subscribers play a crucial role in maintaining transparent communication during service disruptions.++**Key functions of subscribers:**+- Receive automated alerts when monitor statuses change or incidents are updated.+- Stay informed about service health without actively monitoring the status page.+- Choose preferred notification channels for receiving updates.++## Subscription Process++Users typically subscribe to a status page's updates through a dedicated interface provided on the status page itself. The process involves:++1. **Inputting Contact Information:** Providing an email address, phone number, or other contact details depending on the available notification channels.+2. **Opt-in Confirmation:** Confirming their subscription, often through a verification link sent to the provided contact to prevent unwanted subscriptions.+3. **Channel Selection (Optional):** Selecting which specific notification channels (e.g., email, SMS, Slack webhook) they wish to receive updates through, if multiple options are available.++## Notification Types Received++Subscribers receive notifications for key events affecting the monitored services linked to the status page:++- **Incident Creation:** When a new incident is detected and published.+- **Incident Updates:** When status reports are published for an ongoing incident (e.g., status changes from `investigating` to `identified`, `monitoring`, or `resolved`).+- **Monitor Status Changes:** Direct alerts for individual monitor status changes if configured to do so (less common for public subscribers).++## Subscriber Management++Status page administrators can manage their subscriber lists, including:++- **Viewing Subscribers:** Accessing a list of all active subscribers for a status page.+- **Adding/Removing Subscribers:** Manually adding or removing subscribers.+- **Communication:** Sending ad-hoc notifications to the subscriber list (if supported by the platform).++## Related resources++- **[Status Page Reference](/reference/status-page)** - Detailed information on managing and configuring status pages.+- **[Notification Channels Reference](/reference/notification)** - Technical specifications for the various notification delivery methods.+- **[Incident Reference](/reference/incident)** - Information about incident creation and management.diff --git a/apps/docs/src/content/docs/reference/tcp-monitor.mdx b/apps/docs/src/content/docs/reference/tcp-monitor.mdxindex 053cbfa6d..b47fa78d7 100644--- a/apps/docs/src/content/docs/reference/tcp-monitor.mdx+++ b/apps/docs/src/content/docs/reference/tcp-monitor.mdx@@ -1,19 +1,38 @@----title: TCP Monitor+title: TCP Monitor Reference+description: Complete technical specification for TCP service monitoring.---+## Overview-A TCP Monitor is a component that allows you to monitor the status of your services.+A TCP Monitor is a component that establishes a connection to a specified TCP endpoint (IP address and port) to verify its reachability and responsiveness. This is fundamental for monitoring the availability of services that communicate over TCP, such as databases, mail servers, and custom network services.++**Use cases:**+- Database server availability checks (e.g., PostgreSQL, MySQL).+- Mail server (SMTP, IMAP, POP3) reachability.+- Custom application service port monitoring.+- Validating network connectivity to specific endpoints.## Configuration### URI-The url of the endpoint you want to monitor e.g `openstat.us:443`+**Type:** String (required)+**Format:** Hostname or IP address with port (e.g., `example.com:8080`, `192.168.1.1:22`)++The endpoint of the TCP service you want to monitor. This includes the hostname or IP address and the port number.++**Examples:**+- `openstat.us:443`+- `db.internal:5432`+- `10.0.0.5:3306`### Regions-The regions where we are triggering the HTTP request.+**Type:** Array of Strings (required)+**Format:** Region identifiers (e.g., `iad`, `jnb`)++The geographical regions from which the TCP connection attempt will be initiated. This allows for verification of service availability and network latency across different global locations.__Africa__@@ -69,25 +88,64 @@ __Oceania__### Frequency-The check interval, we support the following frequencies:-- 30 seconds-- 1 minute-- 5 minutes-- 10 minutes-- 30 minutes-- 1 hour+**Type:** String (required)+**Format:** Duration string (e.g., `30s`, `1m`, `1h`)++The interval at which the TCP monitor will attempt to connect to the target URI. Supported 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`++**Type:** Duration (optional)+**Default:** `45 seconds`++The maximum duration to wait for a successful TCP connection. If the connection cannot be established within this time, the check is considered a failure.+#### Degraded-The duration for which the HTTP request is considered degraded.++**Type:** Duration (optional)++The duration after which a TCP connection attempt is considered to be in a degraded performance state. This allows for early warning of network latency or service slowdowns.### Retry-The number of retries for the HTTP request. Default: `3`++**Type:** Integer (optional)+**Default:** `3`++The number of times the monitor will automatically retry a failed TCP connection attempt before reporting a definitive error. For example: `3`### OpenTelemetry-#### OTPL Endpoint-The endpoint we use to export the metrics. We only support HTTP endpoint.++Configures the export of monitoring metrics to an OpenTelemetry-compatible observability platform.++#### OTLP Endpoint++**Type:** String (optional)+**Protocol:** HTTP only++The OTLP (OpenTelemetry Protocol) endpoint URL where collected metrics should be exported. Only HTTP endpoints are supported for metric export.+#### OTLP Headers-The headers we use to export the metrics to your otlp endpoint.++**Type:** Key-value pairs (optional)++Custom headers to include when sending metrics to your OTLP endpoint. Commonly used for authentication or tenant identification.++**Common example:**+```+Authorization: Bearer <your_token>+```++## Related resources++- **[Create Your First Monitor](/tutorial/how-to-create-monitor)** - Step-by-step tutorial on setting up a monitor.+- **[Monitoring Overview](/monitoring/overview)** - Conceptual overview of OpenStatus monitoring capabilities.+- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - Detailed information on all metrics and data points collected by monitors.+- **[CLI Reference](/reference/cli-reference)** - Guide to managing OpenStatus monitors programmatically using the command-line interface.diff --git a/apps/docs/src/content/docs/reference/terraform.mdx b/apps/docs/src/content/docs/reference/terraform.mdxindex 658f60601..5054ea529 100644--- a/apps/docs/src/content/docs/reference/terraform.mdx+++ b/apps/docs/src/content/docs/reference/terraform.mdx@@ -1,27 +1,127 @@----title: Terraform Provider-description:- "Use OpenStatus Terraform provider to manage your monitors and status page."+title: Terraform Provider Reference+description: Technical specification for the OpenStatus Terraform Provider.----Here you can find the official OpenStatus Terraform provider. This provider-allows you to manage your monitors and status page using Terraform.+## Overview-https://registry.terraform.io/providers/openstatusHQ/openstatus/latest+The OpenStatus Terraform provider enables you to manage your OpenStatus monitors and status pages programmatically using HashiCorp Terraform. This allows for Infrastructure as Code (IaC) practices, version control, and automated deployment of your monitoring configurations.-## Usage+**Key capabilities:**+- Define and manage OpenStatus monitors as Terraform resources.+- Automate the deployment and updates of monitoring configurations.+- Integrate OpenStatus into your existing IaC workflows.+## Installation++To use the OpenStatus Terraform provider, declare it in your Terraform configuration file (`.tf`). Terraform will automatically download and install the provider when you run `terraform init`.++```terraform+terraform {+ required_providers {+ openstatus = {+ source = "openstatusHQ/openstatus"+ version = "~> 0.1" # Use the latest version+ }+ }+}```++For the latest provider version, refer to the [official Terraform Registry](https://registry.terraform.io/providers/openstatusHQ/openstatus/latest).++## Provider Configuration++The OpenStatus Terraform provider requires authentication via an API token.++### `openstatus_api_token`++**Type:** String (required)+**Description:** Your OpenStatus API Access Token. This token is used to authenticate your Terraform requests with the OpenStatus API.++**Example:**++```terraformprovider "openstatus" {- openstatus_api_token= "YOUR_API_TOKEN"+ openstatus_api_token = "YOUR_OPENSTATUS_API_TOKEN"+}+```++## Resources++The provider currently supports managing `openstatus_monitor` resources.++### `openstatus_monitor`++Manages an OpenStatus monitor. This resource allows you to define and control the parameters of a synthetic monitor.++**Arguments:**++| Argument | Type | Required | Default | Description |+| :------------ | :-------------------- | :------- | :------ | :---------------------------------------------------------------------------------------------------------------------------------------------- |+| `url` | `string` | Yes | | The URL or URI of the endpoint to be monitored. Format depends on the monitor type (e.g., full URL for HTTP, host:port for TCP). |+| `regions` | `list(string)` | Yes | | A list of region identifiers (e.g., `"iad"`, `"jnb"`) from where the monitor checks will be performed. |+| `periodicity` | `string` | Yes | | The frequency at which the monitor will perform checks. Supported values: `"30s"`, `"1m"`, `"5m"`, `"10m"`, `"30m"`, `"1h"`. |+| `name` | `string` | Yes | | A human-readable name for the monitor. |+| `active` | `bool` | Yes | | Specifies whether the monitor is active (`true`) or paused (`false`). |+| `description` | `string` (optional) | No | `""` | A detailed description of the monitor's purpose or configuration. |+| `monitor_type` | `string` | Yes | | The type of monitor to create. Supported values: `"HTTP"`, `"TCP"`, `"DNS"` |+| `method` | `string` (optional) | No | `"GET"` | (HTTP monitors only) The HTTP method to use for the request (e.g., `"GET"`, `"POST"`). |+| `body` | `string` (optional) | No | `""` | (HTTP monitors only) The request body to send for `POST`, `PUT`, `PATCH` methods. |+| `headers` | `map(string)` (optional)| No | `{}` | (HTTP monitors only) A map of custom HTTP headers to include with the request. |+| `timeout` | `string` (optional) | No | `"45s"` | The maximum duration to wait for a response. Format: duration string (e.g., `"30s"`, `"1m"`). |+| `degraded_after`| `string` (optional) | No | `""` | The duration after which a response is considered degraded. Format: duration string. |+| `retries` | `number` (optional) | No | `3` | The number of times the monitor will retry a failed check. |+| `public` | `bool` (optional) | No | `false` | Controls whether monitor data is accessible on your public status page. |+| `otlp_endpoint`| `string` (optional) | No | `""` | The OTLP (OpenTelemetry Protocol) endpoint URL for exporting metrics. |+| `otlp_headers`| `map(string)` (optional)| No | `{}` | Custom headers to include when exporting metrics to your OTLP endpoint. |++**Example Usage:**++```terraform+resource "openstatus_monitor" "my_website_monitor" {+ name = "My Website Availability"+ description = "Checks the main website for uptime and response time."+ url = "https://www.example.com"+ monitor_type = "HTTP"+ method = "GET"+ regions = ["us-east-1", "eu-west-1"]+ periodicity = "1m"+ active = true+ public = true+ timeout = "60s"+}++resource "openstatus_monitor" "internal_api_monitor" {+ name = "Internal API Health Check"+ description = "Monitors the health of a critical internal API."+ url = "https://api.internal.corp:8443/health"+ monitor_type = "HTTP"+ method = "GET"+ regions = ["private-location-id"]+ periodicity = "5m"+ active = true+ public = false+ headers = {+ "Authorization" = "Bearer ${var.internal_api_token}"+ "Accept" = "application/json"+ }}-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"+resource "openstatus_monitor" "database_port_monitor" {+ name = "Database TCP Port Check"+ description = "Ensures the PostgreSQL port is open and reachable."+ url = "db.example.com:5432"+ monitor_type = "TCP"+ regions = ["us-west-2"]+ periodicity = "30s"+ active = true}```++## Related resources++- **[OpenStatus Monitoring Overview](/monitoring/overview)** - Learn more about monitoring concepts in OpenStatus.+- **[HTTP Monitor Reference](/reference/http-monitor)** - Detailed specification for HTTP monitor configuration.+- **[TCP Monitor Reference](/reference/tcp-monitor)** - Detailed specification for TCP monitor configuration.+- **[DNS Monitor Reference](/reference/dns-monitor)** - Detailed specification for DNS monitor configuration.+- **[CLI Reference](/reference/cli-reference)** - Manage monitors using the OpenStatus command-line interface.diff --git a/apps/docs/src/content/docs/status-page/advanced/badge.mdx b/apps/docs/src/content/docs/status-page/advanced/badge.mdxdeleted file mode 100644index 1e51ab413..000000000--- a/apps/docs/src/content/docs/status-page/advanced/badge.mdx+++ /dev/null@@ -1,35 +0,0 @@-----title: Badge-description: "How to embed the status page badge on your website or GitHub README"------You can embed the status page badge on your website or GitHub README to show the-current status of your services.--<a href="https://status.openstatus.dev">- <img src="https://status.openstatus.dev/badge" />-</a>--Copy the following code and paste it into your website or GitHub README:--```html-<img src="https://YOUR-SLUG.openstatus.dev/badge" />-```--If you want the dark version of the badge, you can use the following URL:--```html-<img src="https://YOUR-SLUG.openstatus.dev/badge?theme=dark" />-```--You can also customize the size of the badge by adding a `size` parameter:--- `sm`-- `md`-- `lg`-- `xl`---```html-<img src="https://YOUR-SLUG.openstatus.dev/badge?theme=dark&size=xl" />-```\ No newline at end of filediff --git a/apps/docs/src/content/docs/status-page/advanced/custom-domain.mdx b/apps/docs/src/content/docs/status-page/advanced/custom-domain.mdxindex 04226b6d7..129fac683 100644--- a/apps/docs/src/content/docs/status-page/advanced/custom-domain.mdx+++ b/apps/docs/src/content/docs/status-page/advanced/custom-domain.mdx@@ -1,6 +1,6 @@---title: Custom Domain-description: "How to connect a custom domain to your status page in OpenStatus"+description: "How to connect a custom domain to your status page in openstatus"---import { Aside } from '@astrojs/starlight/components';@@ -9,4 +9,4 @@ import { Aside } from '@astrojs/starlight/components';To connect a custom domain to your status page: _Select a status page → Domain →_.-You will be asked to enter your custom domain. And we will provide you with a DNS record to add to your domain provider.\ No newline at end of file+You will be asked to enter your custom domain. And we will provide you with a DNS record to add to your domain provider.diff --git a/apps/docs/src/content/docs/status-page/advanced/description.mdx b/apps/docs/src/content/docs/status-page/advanced/description.mdxindex bea365587..6d1762d45 100644--- a/apps/docs/src/content/docs/status-page/advanced/description.mdx+++ b/apps/docs/src/content/docs/status-page/advanced/description.mdx@@ -1,6 +1,6 @@---title: Description-description: "How to set a custom description for your status page in OpenStatus"+description: "How to set a custom description for your status page in openstatus"---import { Image } from 'astro:assets';@@ -17,6 +17,5 @@ To add a custom description for your status page: _Select a status page → S<Imagesrc={StatusPage}- alt="OpenStatus status page"+ alt="openstatus status page"/>-diff --git a/apps/docs/src/content/docs/status-page/advanced/icon.mdx b/apps/docs/src/content/docs/status-page/advanced/icon.mdxindex deb82b0f8..b04529523 100644--- a/apps/docs/src/content/docs/status-page/advanced/icon.mdx+++ b/apps/docs/src/content/docs/status-page/advanced/icon.mdx@@ -1,6 +1,6 @@---title: Icon-description: "How to set a custom icon for your status page in OpenStatus"+description: "How to set a custom icon for your status page in openstatus"---import { Image } from 'astro:assets';@@ -16,5 +16,5 @@ To add a custom favicon for your status page: _Select a status page → Setti<Imagesrc={StatusPage}- alt="OpenStatus status page"+ alt="openstatus status page"/>diff --git a/apps/docs/src/content/docs/status-page/advanced/monitors.mdx b/apps/docs/src/content/docs/status-page/advanced/monitors.mdxindex 76b16de16..77302acdd 100644--- a/apps/docs/src/content/docs/status-page/advanced/monitors.mdx+++ b/apps/docs/src/content/docs/status-page/advanced/monitors.mdx@@ -1,6 +1,6 @@---title: Monitors-description: "How to connect your monitors for your status page in OpenStatus"+description: "How to connect your monitors for your status page in openstatus"---Connect your created monitors to your status page to display the current status of your services.@@ -21,4 +21,4 @@ If you want to share all your monitor metrics with your users, you can make yourTo make a monitor public: _Select a monitor → Settings → Danger → Toggle Public monitor.-You can see an example of a public monitor at [https://status.openstatus.dev/monitors/1](https://status.openstatus.dev/monitors/1).\ No newline at end of file+You can see an example of a public monitor at [https://status.openstatus.dev/monitors/1](https://status.openstatus.dev/monitors/1).diff --git a/apps/docs/src/content/docs/status-page/advanced/password.mdx b/apps/docs/src/content/docs/status-page/advanced/password.mdxindex 547ee1d2f..a15190a24 100644--- a/apps/docs/src/content/docs/status-page/advanced/password.mdx+++ b/apps/docs/src/content/docs/status-page/advanced/password.mdx@@ -1,6 +1,6 @@---title: Password protection-description: "How to password protect your status page in OpenStatus"+description: "How to password protect your status page in openstatus"---import { Aside } from '@astrojs/starlight/components';@@ -12,4 +12,3 @@ You can password protect your status page to restrict access to it.To change toggle the protection or change password of your status page: _Select a status page → Settings → Visibility_.The password is stored stored unencrypted in our database and can be shared via `password` search param in the URL, e.g. `https://statuspage.openstatus.dev?password=top-secret`. We recommend using a unique password for your status page.-diff --git a/apps/docs/src/content/docs/status-page/advanced/widget.mdx b/apps/docs/src/content/docs/status-page/advanced/widget.mdxdeleted file mode 100644index d10da0771..000000000--- a/apps/docs/src/content/docs/status-page/advanced/widget.mdx+++ /dev/null@@ -1,175 +0,0 @@-----title: Public Status Widget-description: "How to embed the public status widget in your React application"-----import { Aside } from '@astrojs/starlight/components';--import { Image } from 'astro:assets';--import Widget from '../../../../assets/status-widget/widget-example.png';----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-```--<Aside>- 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](/tools/react).-</Aside>--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.--- <Image- src={Widget}- alt="Status Widget"- />----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>- );-}-```diff --git a/apps/docs/src/content/docs/status-page/overview.mdx b/apps/docs/src/content/docs/status-page/overview.mdxindex 03cbc7f2b..d2334b399 100644--- a/apps/docs/src/content/docs/status-page/overview.mdx+++ b/apps/docs/src/content/docs/status-page/overview.mdx@@ -1,6 +1,6 @@---title: Status page-description: "Discover what is a status page in OpenStatus"+description: "Discover what is a status page in openstatus"---import { Image } from 'astro:assets';@@ -8,7 +8,7 @@ import StatusPage from '../../../assets/status-page/status-page.png';<Imagesrc={StatusPage}- alt="OpenStatus status page"+ alt="openstatus status page"/>@@ -19,7 +19,6 @@ A status page is a public page that displays the status and performance of yourservices. It shows the current status of your services and the history ofincidents.-You can create a status page with OpenStatus and display the status of your synthetic checks.+You can create a status page with openstatus and display the status of your synthetic checks.You can see our own status page at [https://status.openstatus.dev](https://status.openstatus.dev).-diff --git a/apps/docs/src/content/docs/tools/terraform.mdx b/apps/docs/src/content/docs/tools/terraform.mdxindex 658f60601..45b86ec76 100644--- a/apps/docs/src/content/docs/tools/terraform.mdx+++ b/apps/docs/src/content/docs/tools/terraform.mdx@@ -1,10 +1,10 @@---title: Terraform Providerdescription:- "Use OpenStatus Terraform provider to manage your monitors and status page."+ "Use openstatus Terraform provider to manage your monitors and status page."----Here you can find the official OpenStatus Terraform provider. This provider+Here you can find the official openstatus Terraform provider. This providerallows you to manage your monitors and status page using Terraform.https://registry.terraform.io/providers/openstatusHQ/openstatus/latestdiff --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.mdxindex 61cf557d3..6e09e5b48 100644--- 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@@ -1,31 +1,52 @@---title: Get Started with openstatus CLI+description: "Step-by-step tutorial to install and use the openstatus CLI for monitoring as code"---import { Image } from 'astro:assets';import CLI from '../../../assets/tutorial/get-started-with-openstatus-cli/CLI.png';+## What you'll learn++In this tutorial, you'll learn how to use the openstatus CLI to manage your monitors as code. This enables you to version control your monitoring configuration, automate deployments, and implement GitOps workflows.++### Prerequisites++- An openstatus account+- Command line experience+- API token from your openstatus workspace (Settings → API)++### What you'll build++By the end of this tutorial, you'll have:+- openstatus CLI installed on your system+- Monitors exported to a YAML configuration file+- Understanding of monitoring as code workflows+- Ability to manage monitors programmatically+<Imagesrc={CLI}- alt="openstatus CLI"+ alt="openstatus CLI in action showing monitor management"/>## Installation+Install the openstatus CLI to manage your monitors directly from code.-Install the OpenStatus CLI to set up your monitors straight in your code.+### macOS-### OS X+Using Homebrew (recommended):```bashbrew install openstatusHQ/cli/openstatus --cask```-or+Or using the install script:```bashcurl -sSL instl.sh/openstatushq/cli/macos | bash```### Linux+```bashcurl -sSL instl.sh/openstatushq/cli/linux | bash```@@ -36,26 +57,64 @@ curl -sSL instl.sh/openstatushq/cli/linux | bashiwr instl.sh/openstatushq/cli/windows | iex```-## Add API Key+## Configure API authentication-Create an API key in your workspace settings.+Create an API key in your workspace settings (Settings → API), then set it as an environment variable:```bashexport OPENSTATUS_API_TOKEN=<your-api-token>```-## Import Monitors+**Tip**: Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) to persist across sessions.++## Import existing monitors-Import monitors from your workspace to a YAML file.+Start by importing your existing monitors from your workspace to a YAML file:```bashopenstatus monitors import```-### Manage Monitors+This creates an `openstatus.yaml` file containing all your current monitors. This file becomes your single source of truth for monitoring configuration.-Add, remove, or update monitors from a YAML file and apply your changes.+## Manage monitors as code++Now you can add, remove, or update monitors in the YAML file and apply your changes:```bashopenstatus monitors apply```++The CLI will show you a diff of changes before applying them, ensuring you're aware of what will be modified.++## What you've accomplished++Excellent work! You've successfully:+- ✅ Installed the openstatus CLI+- ✅ Configured API authentication+- ✅ Imported monitors to a YAML file+- ✅ Learned the monitoring as code workflow++## What's next?++Now that you have the CLI set up, you can:++- **[Monitor Your MCP Server](/guides/how-to-monitor-mcp-server/)** - Example of CLI-based monitor configuration+- **[Monitoring as Code](/monitoring/monitoring-as-code)** - Learn about the YAML configuration format+- **[CLI Reference](/reference/cli-reference)** - Complete command documentation+- **[Set up CI/CD](/guides/how-to-run-synthetic-test-github-action/)** - Automate monitoring in your pipeline++### Advanced workflows++With the CLI, you can:+- Version control your monitoring configuration with Git+- Review monitoring changes in pull requests+- Automate monitor creation for new services+- Sync monitors across multiple environments+- Implement GitOps for infrastructure monitoring++## Learn more++- **[Monitoring as Code Concept](/concept/uptime-monitoring-as-code)** - Why manage monitors as code+- **[CLI Reference](/reference/cli-reference)** - All available commands+- **[YAML Configuration Examples](https://github.com/openstatusHQ/cli-template)** - Sample configurationsdiff --git a/apps/docs/src/content/docs/tutorial/getting-started.mdx b/apps/docs/src/content/docs/tutorial/getting-started.mdxindex 92130c767..7dc18aeb7 100644--- a/apps/docs/src/content/docs/tutorial/getting-started.mdx+++ b/apps/docs/src/content/docs/tutorial/getting-started.mdx@@ -1,11 +1,39 @@----title: Getting Started+title: Getting Started with Tutorials+description: Step-by-step lessons to learn openstatus from the ground up+sidebar:+ label: Getting Started+ order: 1----Here are some tutorials to help you get started with OpenStatus:+## 📚 Tutorials-- [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)-- [How to configure a status page?](/tutorial/how-to-configure-status-page)-- [How to create a private location? (beta)](/tutorial/how-to-create-private-location)-- [Get Started with openstatus CLI](/tutorial/get-started-with-openstatus-cli)+### What you'll learn++Our tutorials are designed to help you:+- Get your first monitor up and running+- Create and configure status pages+- Set up monitoring infrastructure+- Use openstatus CLI for automation++### Core Tutorials++Start your journey with openstatus:++- **[Create Your First Monitor](/tutorial/how-to-create-monitor)** - Learn the fundamentals by setting up uptime monitoring for your first endpoint+- **[Create a Status Page](/tutorial/how-to-create-status-page)** - Build a public status page to communicate service health to your users+- **[Configure Your Status Page](/tutorial/how-to-configure-status-page)** - Customize your status page with monitors, domains, and protection++### Advanced Tutorials++Once you're comfortable with the basics:++- **[Create a Private Location (Beta)](/tutorial/how-to-create-private-location)** - Set up monitoring from your own infrastructure+- **[Get Started with openstatus CLI](/tutorial/get-started-with-openstatus-cli)** - Automate monitor management with our command-line tool++### What's next?++After completing these tutorials, you'll be ready to:+- Explore [how-to guides](/guides/getting-started/) for specific tasks and advanced scenarios+- Dive into [explanations](/concept/getting-started/) to understand the concepts behind the features+- Reference our [technical documentation](/reference) for detailed specificationsdiff --git a/apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdx b/apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdxindex d86e12762..09add01e1 100644--- a/apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdx+++ b/apps/docs/src/content/docs/tutorial/how-to-configure-status-page.mdx@@ -1,6 +1,6 @@----title: How to configure a status page?-description: "How to configure a status page"+title: Configure Your Status Page+description: "A step-by-step tutorial to customize and configure your status page"---import { Image } from 'astro:assets';@@ -14,9 +14,29 @@ import StatusPageBeta2 from '../../../assets/tutorial/configure-status-page/statimport StatusPageBeta3 from '../../../assets/tutorial/configure-status-page/status-page-beta-3.png';import StatusPageBeta4 from '../../../assets/tutorial/configure-status-page/status-page-beta-4.png';-We are releasing a new version of our status pages.+## What you'll learn-Explore the themes: [https://themes.openstatus.dev](https://themes.openstatus.dev)+In this tutorial, you'll learn how to customize your status page's appearance and behavior. You'll explore different display options, themes, and configuration settings to create a status page that matches your brand and communication style.++### Prerequisites++- An openstatus account+- A status page already created (see [Create a Status Page](/tutorial/how-to-create-status-page))+- At least one monitor added to your status page++### What you'll build++By the end of this tutorial, you'll have:+- A customized status page with your preferred theme+- Configured status trackers displaying data your way+- Links to important resources+- Preview and live configuration experience++## Status Page Redesign (Beta)++We are releasing a new version of our status pages with enhanced customization options.++Explore available themes: [https://themes.openstatus.dev](https://themes.openstatus.dev)## Get started@@ -101,11 +121,33 @@ Let's have a closer look to your status page header navigation:**Contact URL**: If filled out, you will see a `Message` icon that users can click to forward them to a contact page. This can also be an email client by starting the input with `mailto:` (e.g. `mailto:[email protected]`).----We are adding some additional features. Feel free to let us know what's missing!+## What you've accomplished++Excellent work! You've successfully:+- ✅ Enabled and configured the new status page design (beta)+- ✅ Customized status tracker display options+- ✅ Explored and applied theme settings+- ✅ Added navigation links to your status page+- ✅ Previewed changes before making them live++## What's next?++Now that your status page is configured, you can:++- **[Configure Notifications](/monitoring/customization/notification)** - Alert your team when issues occur+- **[Best Practices for Status Pages](/concept/best-practices-status-page)** - Learn effective incident communication+- **[Add Status Subscribers](/reference/subscriber)** - Let users subscribe to updates++### Learn more++- **[Status Page Reference](/reference/status-page)** - Complete configuration options+- **[Uptime Calculation Values](/concept/uptime-calculation-and-values)** - How uptime percentages work+- **[See Examples](https://www.openstatus.dev/showcase)** - Browse other status pages for inspiration+## Video Tutorial<ShowcaseYouTubediff --git a/apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx b/apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdxindex 7b19487cd..a58166380 100644--- a/apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx+++ b/apps/docs/src/content/docs/tutorial/how-to-create-monitor.mdx@@ -1,6 +1,6 @@---title: Create Your First Monitor-description: "How to create your first monitor with OpenStatus"+description: "A step-by-step tutorial to create your first monitor with openstatus"---import { Image } from 'astro:assets';@@ -11,9 +11,21 @@ import createMonitor2 from '../../../assets/tutorial/create-monitor/create-monitimport { ShowcaseYouTube } from 'starlight-showcases'+## What you'll learn+In this tutorial, you'll learn how to create your first monitor an automated watchdog for your services. A monitor periodically checks your endpoints to ensure they are available, performant, and returning the correct data. Think of it as a `curl` command that runs 24/7, providing continuous insights into the health of your application.-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.+### Prerequisites++- An openstatus account (free tier available at [openstatus.dev](https://www.openstatus.dev))+- A URL endpoint to monitor (can be your own service or any public URL)++### What you'll build++By the end of this tutorial, you'll have:+- A working uptime monitor checking your endpoint every minute+- Real-time metrics showing response time and status codes+- Understanding of how to customize HTTP requests for different scenarios## Get Started in 1 Minute@@ -85,7 +97,7 @@ You can add any number of custom HTTP headers to your request. This is particula- **Simulating Clients:** Adding a User-Agent header to simulate traffic from a specific browser or device.Heads Up: We've got your User-Agent covered!- OpenStatus automatically includes the `"User-Agent": "OpenStatus/1.0"` header in every request. This makes it easy to identify and filter out our monitoring traffic from your server logs or analytics.+ openstatus automatically includes the `"User-Agent": "openstatus/1.0"` header in every request. This makes it easy to identify and filter out our monitoring traffic from your server logs or analytics.@@ -94,6 +106,29 @@ You can add any number of custom HTTP headers to your request. This is particula### Monitoring Third-Party Endpoints<Aside>If you're monitoring a URL you don't own (like `google.com` or a partner API), your requests might be blocked by firewalls or rate limiters (e.g., Cloudflare). This is a security measure on their end to prevent scraping or denial-of-service attacks.</Aside>+## What you've accomplished++Congratulations! You've successfully:+- ✅ Created your first uptime monitor+- ✅ Configured basic HTTP monitoring settings+- ✅ Learned about customizing requests with methods, headers, and body+- ✅ Understood key monitoring metrics (response time, status codes, timing breakdown)++## What's next?++Now that you have a monitor running, you can:++- **[Create a Status Page](/tutorial/how-to-create-status-page)** - Share your service status publicly with users+- **[Set Up Alerting](/monitoring/customization/notification)** - Get notified when your service goes down+- **[Configure Assertions](/monitoring/customization/assertions)** - Validate response content, not just status codes+- **[Add Multiple Regions](/monitoring/customization/locations)** - Monitor from different global locations++### Learn more++- **[Understanding Uptime Monitoring](/concept/uptime-monitoring)** - Deep dive into monitoring concepts+- **[Monitor Data Collected](/monitoring/monitor-data-collected)** - What metrics we track+- **[HTTP Monitor Reference](/reference/http-monitor)** - Complete technical specifications+## Video Tutorialdiff --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.mdxindex b4521db47..5dfee0562 100644--- 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@@ -1,6 +1,6 @@----title: How to create a status page?-description: "How to create a status page in OpenStatus"+title: Create a Status Page+description: "A step-by-step tutorial to create and publish your first status page"---import { Image } from 'astro:assets';@@ -9,9 +9,23 @@ import CreateStatusPage1 from '../../../assets/tutorial/create-status-page/creatimport CreateStatusPage2 from '../../../assets/tutorial/create-status-page/create-status-page-2.png';+## What you'll learn+In this tutorial, you'll create a public status page to communicate your service's health to users. A status page is a transparent way to show real-time uptime information and keep your users informed during incidents.-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.+### Prerequisites++- An openstatus account+- At least one monitor created (see [Create Your First Monitor](/tutorial/how-to-create-monitor))++### What you'll build++By the end of this tutorial, you'll have:+- A public status page showing your service health+- Monitors displayed on your status page+- Understanding of privacy and security options++This tutorial will guide you through the process of creating a status page in openstatus. A status page is a web page that displays the status of your services, building trust with your users through transparency.## Get started@@ -42,9 +56,30 @@ You need to add monitors to your status page. Monitors are used to check the sta#### 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.+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 ProtectionYou can add password protection to your status page. Password protection allows you to restrict access to your status page to only authorized users.++## What you've accomplished++Great work! You've successfully:+- ✅ Created your first status page+- ✅ Added monitors to display service health+- ✅ Learned about custom domains and password protection++## What's next?++Now that you have a basic status page, you can:++- **[Configure Your Status Page](/tutorial/how-to-configure-status-page)** - Customize appearance and add more features+- **[Configure Notifications](/monitoring/customization/notification)** - Alert your team when issues occur+- **[Best Practices for Status Pages](/concept/best-practices-status-page)** - Learn how to communicate effectively++### Learn more++- **[Status Page Reference](/reference/status-page)** - Complete configuration options+- **[Understanding Uptime Values](/concept/uptime-calculation-and-values)** - How uptime is calculated+- **[Status Page Examples](https://www.openstatus.dev/showcase)** - See status pages from other usersdiff --git a/apps/docs/src/content/docs/tutorials.mdx b/apps/docs/src/content/docs/tutorials.mdxdeleted file mode 100644index 998dfd39c..000000000--- a/apps/docs/src/content/docs/tutorials.mdx+++ /dev/null@@ -1,4 +0,0 @@-----title: Tutorials-description: Learn more about the project I’m working on.----diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex c5e6e395d..5af7669d1 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -1805,6 +1805,8 @@ importers:specifier: 5.9.3version: 5.9.3+ packages/react/dist: {}+packages/regions:dependencies:zod: