diff --git a/apps/web/src/content/pages/docs/concept/best-practices-status-page.mdx b/apps/web/src/content/pages/docs/concept/best-practices-status-page.mdx index 74d916ca..1c977ec1 100644 --- a/apps/web/src/content/pages/docs/concept/best-practices-status-page.mdx +++ b/apps/web/src/content/pages/docs/concept/best-practices-status-page.mdx @@ -7,16 +7,16 @@ description: "Understanding how to communicate effectively during incidents and ``` +------------------------------------------------+ -| openstatus Status Page | +| openstatus status page | +------------------------------------------------+ -| Service Name | Status | Uptime | -+-------------------+--------+-------------------+ -| Web Server | ✅ OK | 99.9% | -| Database | ✅ OK | 99.8% | -| API Gateway | ⚠️ Degraded | 99.5% | -| Monitoring | ✅ OK | 100% | -| Payment Processing| ✅ OK | 99.7% | -+-------------------+--------+-------------------+ +| Service name | Status | Uptime | ++-------------------+------------+---------------+ +| Web Server | OK | 99.9% | +| Database | OK | 99.8% | +| API Gateway | Degraded | 99.5% | +| Monitoring | OK | 100% | +| Payment Processing| OK | 99.7% | ++-------------------+------------+---------------+ | Incidents: | | | | - Degraded performance on API Gateway due | @@ -36,94 +36,84 @@ When done right, a status page: This article explores the principles that make a status page an effective tool for building trust. -## Principles of Effective Status Pages +## Principles of effective status pages -### Maintain Transparency and Honesty +### Maintain transparency and honesty A status page's effectiveness hinges on being a reliable source of truth. Be upfront about issues, even minor ones. Hiding problems erodes user trust and can lead to frustration and a higher support load. -- **Communicate Clearly:** Use simple, non-technical language. Your users shouldn't need a technical dictionary to understand the impact of an issue. +- **Communicate clearly** — use simple, non-technical language. Your users shouldn't need a technical dictionary to understand the impact of an issue. +- **Be timely** — update the page as soon as an incident is confirmed. Provide regular, predictable updates throughout the resolution process, even if the only update is "we're still working on it." -- **Be Timely:** Update the page as soon as an incident is confirmed. Provide regular, predictable updates throughout the resolution process, even if the only update is "we're still working on it." - -### Automate Where Possible +### Automate where possible Manual updates during a high-stress outage are prone to error and can be slow. Automation ensures that your status page reflects reality quickly and accurately. -- **Integrate Monitoring Tools:** Your status page should be directly connected to your internal monitoring and alerting systems. When a metric crosses a threshold (e.g., a high error rate), the status page can be updated automatically to reflect a degraded state. - -- **Use an API:** We provide APIs that allow you to programmatically update component statuses and post new incidents, integrating your status page into your incident response workflows. +- **Integrate monitoring tools** — your status page should be directly connected to your internal monitoring and alerting systems. When a metric crosses a threshold (e.g., a high error rate), the status page can be updated automatically to reflect a degraded state. +- **Use an API** — we provide APIs that let you programmatically update component statuses and post new incidents, integrating your status page into your incident response workflows. - -### Provide Context-Rich Incident Communication +### Provide context-rich incident communication When an incident occurs, a structured narrative helps users understand the situation. -- **Start with the Impact:** Clearly and concisely state what the problem is from the user's perspective. For example, "Users are currently unable to log in." - -- **Explain the Cause (When Known):** Briefly explain the root cause if you've identified it. Transparency here is key. - -- **Outline Next Steps and ETA:** Explain what is being done to resolve the issue and provide an estimated time to resolution if possible. It's better to give a conservative estimate or no estimate than to give one you can't meet. +- **Start with the impact** — clearly and concisely state what the problem is from the user's perspective. For example, "Users are currently unable to log in." +- **Explain the cause (when known)** — briefly explain the root cause if you've identified it. Transparency here is key. +- **Outline next steps and ETA** — explain what is being done to resolve the issue and provide an estimated time to resolution if possible. It's better to give a conservative estimate or no estimate than to give one you can't meet. A typical incident communication lifecycle looks like this: -- **Investigating:** "We're currently investigating an issue affecting user logins." - -- **Identified:** "We've identified the root cause as a database connection issue and are working on a fix." - -- **Monitoring:** "A fix has been deployed, and we're monitoring the system to ensure stability." - -- **Resolved:** "The issue has been resolved. We will publish a post-mortem within 48 hours." +- **Investigating** — "We're currently investigating an issue affecting user logins." +- **Identified** — "We've identified the root cause as a database connection issue and are working on a fix." +- **Monitoring** — "A fix has been deployed, and we're monitoring the system to ensure stability." +- **Resolved** — "The issue has been resolved. We will publish a post-mortem within 48 hours." - -### Ensure Easy Accessibility +### Ensure easy accessibility Your status page is useless if no one can find it. -- **Prominent Link:** Link to your status page from your application's footer, your main website, and your support documentation. - -- **Custom Domain:** Use a simple, memorable URL like `status.yourcompany.com`. +- **Prominent link** — link to your status page from your application's footer, your main website, and your support documentation. +- **Custom domain** — use a simple, memorable URL like `status.yourcompany.com`. -## Advanced Considerations for Deeper Trust +## Advanced considerations for deeper trust -### Scheduled Maintenance +### Scheduled maintenance Communicating planned downtime is just as important as communicating unexpected incidents. + - Announce maintenance well in advance (e.g., at least 72 hours). - Display upcoming maintenance windows clearly on the status page. - Send reminders to subscribers before maintenance begins. -### Historical Data and Post-Mortems +### Historical data and post-mortems Demonstrate your commitment to reliability by being open about your track record. + - Display historical uptime percentages (e.g., over the last 30/60/90 days). - Link to past incidents and their post-mortems. Being honest about past failures and what you've learned from them is a powerful trust-builder. -### Subscriber Notifications +### Subscriber notifications Allow users to opt-in to the level of communication they want. + - Email notifications for new incidents and resolutions. - SMS for critical alerts (if applicable). - RSS/Atom feeds for users who want to integrate your status into their own monitoring. -## Common Pitfalls to Avoid +## Common pitfalls to avoid -1. **Claiming unrealistic uptime**: Don't claim 100% uptime unless you can back it up. Honesty is better than perfection. -2. **Hiding or downplaying incidents**: Users will find out anyway. It's better they hear it from you. -3. **Using technical jargon**: Write for a broad audience, not just other engineers. -4. **Leaving users in the dark**: During an incident, regular updates are crucial, even if there's no new information. A simple "still investigating" is better than silence. -5. **Hosting your status page on the same infrastructure**: Your status page must be available even when your main service is down. +1. **Claiming unrealistic uptime** — don't claim 100% uptime unless you can back it up. Honesty is better than perfection. +2. **Hiding or downplaying incidents** — users will find out anyway. It's better they hear it from you. +3. **Using technical jargon** — write for a broad audience, not just other engineers. +4. **Leaving users in the dark** — during an incident, regular updates are crucial, even if there's no new information. A simple "still investigating" is better than silence. +5. **Hosting your status page on the same infrastructure** — your status page must be available even when your main service is down. ## Implementing with openstatus -openstatus is designed to make implementing these principles straightforward: - -- **[Create a status page](/docs/tutorial/create-your-first-status-page)** - Get set up in minutes. -- **[Configure your page](/docs/guides/how-to-configure-status-page)** - Customize its appearance to match your brand. -- **[Understand uptime calculations](/docs/concept/uptime-calculation-and-values)** - Be transparent about how you measure uptime. +- **[Create a status page](/docs/tutorial/create-your-first-status-page)** — get set up in minutes. +- **[Configure your page](/docs/guides/how-to-configure-status-page)** — customise its appearance to match your brand. +- **[Understand uptime calculations](/docs/concept/uptime-calculation-and-values)** — be transparent about how you measure uptime. ## Next steps - -- **[Understanding uptime monitoring](/docs/concept/uptime-monitoring)** - Learn more about monitoring what you communicate. -- **[Status page reference](/docs/reference/status-page)** - Dive into technical configuration options. +- **[Understanding uptime monitoring](/docs/concept/uptime-monitoring)** — learn more about monitoring what you communicate. +- **[Status page reference](/docs/reference/status-page)** — dive into technical configuration options. diff --git a/apps/web/src/content/pages/docs/concept/getting-started.mdx b/apps/web/src/content/pages/docs/concept/getting-started.mdx index 45b6be27..9e51c481 100644 --- a/apps/web/src/content/pages/docs/concept/getting-started.mdx +++ b/apps/web/src/content/pages/docs/concept/getting-started.mdx @@ -4,27 +4,21 @@ description: "Understand uptime monitoring, latency vs response time, SLA calcul category: Concepts --- -## Building a solid foundation +This section is dedicated to explanation. It's not about quick fixes or step-by-step instructions — it's here to help you build a deep understanding of uptime monitoring and the principles behind openstatus. -This section of our documentation is dedicated to explanation. It's not about quick fixes or step-by-step instructions. Instead, it's here to help you build a deep understanding of uptime monitoring and the principles behind openstatus. +A solid mental model lets you use the tools more effectively, make better decisions for your own systems, and communicate with your team and stakeholders with clarity. We'll explore the "why" behind the "what" — core concepts, best practices, and the design philosophy that guides the product. -A solid mental model will empower you to use our tools more effectively, make better decisions for your own systems, and communicate with your team and stakeholders with clarity and confidence. +### Core concepts -We'll explore the "why" behind the "what," covering core concepts, best practices, and the design philosophy that guides our development. +- **[Uptime monitoring](/docs/concept/uptime-monitoring)** — what is it, why does it matter, and how does it work? +- **[Uptime calculation and values](/docs/concept/uptime-calculation-and-values)** — a look under the hood at how uptime percentages are calculated and what they truly represent. +- **[Latency vs response time](/docs/concept/latency-vs-response-time)** — untangle the difference between these two critical performance metrics. +- **[Probes, locations, and regions](/docs/concept/probes-and-locations)** — three words that look interchangeable but aren't. +- **[Understanding private locations](/docs/concept/private-locations)** — when to run your own probe and the trade-offs. -### Core Concepts +### Best practices and philosophy -Start here to grasp the fundamental building blocks of uptime monitoring. +- **[Building trust with status pages](/docs/concept/best-practices-status-page)** — how to communicate effectively during incidents and maintain user trust. +- **[Uptime monitoring as code](/docs/concept/uptime-monitoring-as-code)** — the why and how of managing your monitoring configuration in a GitOps workflow. -- **[Uptime Monitoring](/docs/concept/uptime-monitoring)**: What is it, why does it matter, and how does it work? -- **[Uptime Calculation and Values](/docs/concept/uptime-calculation-and-values)**: A look under the hood at how uptime percentages are calculated and what they truly represent. -- **[Latency vs Response Time](/docs/concept/latency-vs-response-time)**: Untangle the difference between these two critical performance metrics. - -### Best Practices & Philosophy - -Learn from experience and understand our approach to modern monitoring. - -- **[Building Trust with Status Pages](/docs/concept/best-practices-status-page)**: How to communicate effectively during incidents and maintain user trust. -- **[Uptime Monitoring as Code](/docs/concept/uptime-monitoring-as-code)**: The why and how of managing your monitoring configuration in a GitOps workflow. - -Have questions or want to discuss these concepts? [Join our community](/docs/help/support) and share your thoughts! +Have questions or want to discuss these concepts? [Join our community](/docs/help/support). diff --git a/apps/web/src/content/pages/docs/concept/latency-vs-response-time.mdx b/apps/web/src/content/pages/docs/concept/latency-vs-response-time.mdx index 8f5da0e9..69b64cdf 100644 --- a/apps/web/src/content/pages/docs/concept/latency-vs-response-time.mdx +++ b/apps/web/src/content/pages/docs/concept/latency-vs-response-time.mdx @@ -39,7 +39,7 @@ Latency is the time it takes for data to travel from its source to its destinati To measure latency, you can monitor endpoints like `/ping` or `/healthcheck` with minimum server processing time. -## What Is Response Time? +## What is response time? ``` openstatus Network Server @@ -59,7 +59,7 @@ To measure latency, you can monitor endpoints like `/ping` or `/healthcheck` wit Response time is the total time from the moment a user's request is sent until the moment the first byte of the server's response is received. It includes both the network latency and the server's processing time. -Response time = Network Latency + Server Processing Time +Response time = network latency + server processing time The server processing time is the duration the server spends on tasks like: @@ -99,28 +99,32 @@ By monitoring both metrics, you can quickly pinpoint whether a performance slowd ### Common scenarios -**Scenario 1: Consistent latency, variable response time** -- Indicates server-side performance issues -- Look at: Database queries, API calls, resource utilization +**Scenario 1: consistent latency, variable response time** -**Scenario 2: High latency from specific regions** -- Indicates geographic network issues -- Solution: Add regional monitoring points or CDN +- Indicates server-side performance issues. +- Look at: database queries, API calls, resource utilisation. -**Scenario 3: Both metrics degrading** -- Could be network saturation or DDoS attack -- Check: Network bandwidth, traffic patterns, security +**Scenario 2: high latency from specific regions** + +- Indicates geographic network issues. +- Solution: add regional monitoring points or a CDN. + +**Scenario 3: both metrics degrading** + +- Could be network saturation or a 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 + +- **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](/docs/tutorial/create-your-first-monitor)** - Start tracking these metrics -- **[Understanding uptime monitoring](/docs/concept/uptime-monitoring)** - Broader monitoring concepts -- **[HTTP monitor reference](/docs/reference/http-monitor)** - Technical specifications +- **[Create your first monitor](/docs/tutorial/create-your-first-monitor)** — start tracking these metrics. +- **[Understanding uptime monitoring](/docs/concept/uptime-monitoring)** — broader monitoring concepts. +- **[HTTP monitor reference](/docs/reference/http-monitor)** — technical specifications. diff --git a/apps/web/src/content/pages/docs/concept/private-locations.mdx b/apps/web/src/content/pages/docs/concept/private-locations.mdx index ef37822e..cab1d0ab 100644 --- a/apps/web/src/content/pages/docs/concept/private-locations.mdx +++ b/apps/web/src/content/pages/docs/concept/private-locations.mdx @@ -6,7 +6,7 @@ description: "What a private location is, when to use one, how it talks to opens A **private location** is a monitoring probe you run on your own infrastructure. Instead of openstatus checking your endpoint from one of its public regions, a container you control performs the check and reports the result back over an outbound connection. -This page explains the model — what a private location *is* and the trade-offs of using one. For the setup walkthrough, see the [private location tutorial](/docs/tutorial/how-to-create-private-location); for fields and the API surface, see the [private location reference](/docs/reference/private-location). +This page explains the model — what a private location *is* and the trade-offs of using one. For the setup walkthrough, see the [private location guide](/docs/guides/how-to-create-private-location); for fields and the API surface, see the [private location reference](/docs/reference/private-location). ## When a private location is the right tool @@ -63,7 +63,7 @@ Both are tracked and expected to land — when they do, the [private location re ## Next steps -- **[Set up a private location](/docs/tutorial/how-to-create-private-location)** — step-by-step deployment of the Docker probe. +- **[Set up a private location](/docs/guides/how-to-create-private-location)** — step-by-step deployment of the Docker probe. - **[Deploy a private probe on Cloudflare Containers](/docs/guides/how-to-deploy-probes-cloudflare-containers)** — a serverless deployment pattern instead of a long-running container. -- **[Private Location Reference](/docs/reference/private-location)** — fields, API surface, and supported operations. -- **[Probes and Locations](/docs/concept/probes-and-locations)** — how the terms "probe", "location", and "region" relate. +- **[Private location reference](/docs/reference/private-location)** — fields, API surface, and supported operations. +- **[Probes and locations](/docs/concept/probes-and-locations)** — how the terms "probe", "location", and "region" relate. diff --git a/apps/web/src/content/pages/docs/concept/probes-and-locations.mdx b/apps/web/src/content/pages/docs/concept/probes-and-locations.mdx index 506b4953..5617c997 100644 --- a/apps/web/src/content/pages/docs/concept/probes-and-locations.mdx +++ b/apps/web/src/content/pages/docs/concept/probes-and-locations.mdx @@ -55,6 +55,6 @@ Three quick scenarios make the distinction concrete: ## Next steps -- **[Location Reference](/docs/reference/location)** — public locations, regions, providers, and the IPs to allowlist. -- **[Understanding Private Locations](/docs/concept/private-locations)** — when to run your own probe and the trade-offs. -- **[Create an Uptime Monitor](/docs/tutorial/how-to-create-monitor)** — applies these concepts to a working monitor. +- **[Location reference](/docs/reference/location)** — public locations, regions, providers, and the IPs to allowlist. +- **[Understanding private locations](/docs/concept/private-locations)** — when to run your own probe and the trade-offs. +- **[Create an uptime monitor](/docs/tutorial/create-your-first-monitor)** — applies these concepts to a working monitor. diff --git a/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdx b/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdx index 29a028c3..4b868ba5 100644 --- a/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdx +++ b/apps/web/src/content/pages/docs/concept/uptime-calculation-and-values.mdx @@ -4,39 +4,32 @@ title: Uptime Calculation and Shared Values description: Understand how openstatus calculates uptime — absolute (duration or requests) and manual modes — and choose which values to share on your status page. --- -Let’s face it - uptime values can be a complete lie if they’re not properly connected to monitoring. +Uptime values can be a complete lie if they're not properly connected to monitoring. openstatus makes uptime transparent and configurable — you decide how it's calculated and which values to share on your status page. -We want to make uptime transparent and configurable. You decide how your uptime is calculated and which values you want to share on your status page. When monitoring an endpoint, a check can end up in one of three states: -- ✅ Success – everything’s fine -- ⚠️ Degraded – slow or partially failing -- ❌ Down – no response or full failure +- **Success** — everything's fine. +- **Degraded** — slow or partially failing. +- **Down** — no response or full failure. -We now offer multiple types of uptime calculation: -- **Absolute** (default): derived directly from your monitoring data - - **Duration**: aggregated from the incidents duration - - **Requests** (default): aggregated from the request values -- **Manual**: for teams that prefer full control over what’s shown +There are two top-level types of uptime calculation: + +- **Absolute** (default) — derived directly from your monitoring data. + - **Duration** — aggregated from the incidents' duration. + - **Requests** (default) — aggregated from the request values. +- **Manual** — for teams that prefer full control over what's shown. **TL;DR** -| Type | Source of Truth | What Users See | Best For | +| Type | Source of truth | What users see | Best for | |-------------|----------------------|-------------------------------------|----------------------------------| -| **Duration** (Absolute) | Incident duration | Time based uptime, proportional colors | Accurate long-term view | -| **Request** (Absolute) | Every ping result | Request-based uptime % | Real-time reflection | +| **Duration** (absolute) | Incident duration | Time-based uptime, proportional colours | Accurate long-term view | +| **Request** (absolute) | Every ping result | Request-based uptime % | Real-time reflection | | **Manual** | Manually set status | Controlled, narrative updates | Transparency without monitoring | -
- -Let’s break them down! - -## Absolute Type - -The absolute type calculates uptime based on actual monitoring results. It’s the most accurate reflection of what’s really happening, and comes in two variants: _Duration_ and _Request_. -Both of these share real data with your users - incidents, degraded states, and historical uptime - but they differ in how they aggregate and display that data. +## Absolute type ---- +The absolute type calculates uptime based on actual monitoring results. It's the most accurate reflection of what's really happening, and comes in two variants: _duration_ and _request_. Both share real data with your users — incidents, degraded states, and historical uptime — but they differ in how they aggregate and display that data. ### Duration @@ -44,35 +37,33 @@ The duration value is calculated from the **total monitoring time and the durati In simple terms: `uptime = (total time - incident duration) / total time` -This means uptime is based on how long something was down, not how many checks failed. Only incident durations are included in the calculation. - -Temporary single-region ping failures (e.g., one location failing once, sometimes this just happens) are not propagated to users - because these often don’t represent a real outage. That’s also why we recommend at least three locations per monitor for redundancy. +This means uptime is based on how long something was down, not how many checks failed. Only incident durations are included in the calculation. -The proportional colors in the status bar are drawn from these duration values. Hovering over a day shows both incidents and status reports, so users can explore what happened. +Temporary single-region ping failures (e.g., one location failing once, sometimes this just happens) are not propagated to users — because these often don't represent a real outage. That's also why we recommend at least three locations per monitor for redundancy. ---- +The proportional colours in the status bar are drawn from these duration values. Hovering over a day shows both incidents and status reports, so users can explore what happened. ### Request -The request value is more straightforward - it looks at each ping result individually. **Every check we run contributes to your uptime score**. +The request value is more straightforward — it looks at each ping result individually. **Every check we run contributes to your uptime score**. In simple terms: `uptime = (success + degraded) / total requests` -This is the current default mode for most openstatus users. It’s simple, data-driven, and updates immediately as new results come in. +This is the current default mode for most openstatus users. It's simple, data-driven, and updates immediately as new results come in. Like with duration, hover cards display incidents and status reports, giving your users a quick overview of recent events. -## Manual Type +## Manual type -The 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. +The 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. This is ideal if: -- you don’t have synthetic monitoring set up yet, -- or you’re sharing updates that aren’t tied to uptime (e.g., service degradation due to external dependencies). + +- you don't have synthetic monitoring set up yet, or +- you're sharing updates that aren't tied to uptime (e.g., service degradation due to external dependencies). In this mode, all displayed uptime values and statuses come from your shared report data, not from active pings. In 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). +> **Note:** the values you define are attached to a status page. You cannot change them per monitor (for now). diff --git a/apps/web/src/content/pages/docs/concept/uptime-monitoring-as-code.mdx b/apps/web/src/content/pages/docs/concept/uptime-monitoring-as-code.mdx index 215d31ad..e8890a27 100644 --- a/apps/web/src/content/pages/docs/concept/uptime-monitoring-as-code.mdx +++ b/apps/web/src/content/pages/docs/concept/uptime-monitoring-as-code.mdx @@ -25,15 +25,11 @@ Instead of clicking buttons, you declare monitors, status pages, and notificatio This approach offers significant advantages: -- **Version Control:** Every change to a monitor lives in Git. You can see who modified what, review diffs, and roll back to a known-good state. Crucial for auditing and troubleshooting. - -- **Automation and Consistency:** Your monitoring setup becomes part of your deployment pipeline. When you ship a new service, its monitors, alerts, and status page components are provisioned automatically alongside it — no risk of forgetting to wire one up. - -- **Collaboration:** A code-based workflow makes peer review natural. A developer opens a pull request that adds a monitor, the team reviews it like any other change, and `terraform plan` shows exactly what will happen before it does. - -- **Scalability:** Managing hundreds of monitors through a UI is impractical. With Terraform, you can use modules, `for_each`, and variables to generate configurations programmatically as your infrastructure grows. - -- **Simplified Auditing:** The current state of every monitor, page, and notification is captured in your `.tf` files. One `terraform plan` shows you any drift between what's declared and what's live. +- **Version control** — every change to a monitor lives in Git. You can see who modified what, review diffs, and roll back to a known-good state. Crucial for auditing and troubleshooting. +- **Automation and consistency** — your monitoring setup becomes part of your deployment pipeline. When you ship a new service, its monitors, alerts, and status page components are provisioned automatically alongside it — no risk of forgetting to wire one up. +- **Collaboration** — a code-based workflow makes peer review natural. A developer opens a pull request that adds a monitor, the team reviews it like any other change, and `terraform plan` shows exactly what will happen before it does. +- **Scalability** — managing hundreds of monitors through a UI is impractical. With Terraform, you can use modules, `for_each`, and variables to generate configurations programmatically as your infrastructure grows. +- **Simplified auditing** — the current state of every monitor, page, and notification is captured in your `.tf` files. One `terraform plan` shows you any drift between what's declared and what's live. ## How it works with openstatus @@ -110,16 +106,14 @@ From there, import the resources into Terraform state and you're managing the ex ## Best practices -1. **Start simple**: Begin with a few monitors, expand as you learn -2. **Use modules**: Wrap common monitor patterns in reusable Terraform modules -3. **Sensitive variables**: Mark API tokens and webhook URLs as `sensitive` and pass them via `TF_VAR_*` env vars or a secrets manager -4. **Review changes**: Always run `terraform plan` and review the diff before applying -5. **Document decisions**: Use commit messages to explain "why" +1. **Start simple** — begin with a few monitors, expand as you learn. +2. **Use modules** — wrap common monitor patterns in reusable Terraform modules. +3. **Sensitive variables** — mark API tokens and webhook URLs as `sensitive` and pass them via `TF_VAR_*` env vars or a secrets manager. +4. **Review changes** — always run `terraform plan` and review the diff before applying. +5. **Document decisions** — use commit messages to explain "why". ## Next steps -Ready to implement monitoring as code? - -- **[Manage openstatus with Terraform](/docs/tutorial/how-to-manage-openstatus-with-terraform-cli)** - End-to-end tutorial -- **[Terraform Provider Reference](/docs/reference/terraform)** - Full resource specification -- **[Monitor Your MCP Server](/docs/guides/how-to-monitor-mcp-server)** - Real-world example +- **[Manage openstatus with Terraform](/docs/guides/how-to-manage-openstatus-with-terraform-cli)** — end-to-end guide. +- **[Terraform provider reference](/docs/reference/terraform)** — full resource specification. +- **[Monitor your MCP server](/docs/guides/how-to-monitor-mcp-server)** — real-world example. diff --git a/apps/web/src/content/pages/docs/concept/uptime-monitoring.mdx b/apps/web/src/content/pages/docs/concept/uptime-monitoring.mdx index 714f9368..f4ebcc9a 100644 --- a/apps/web/src/content/pages/docs/concept/uptime-monitoring.mdx +++ b/apps/web/src/content/pages/docs/concept/uptime-monitoring.mdx @@ -51,7 +51,7 @@ At its core, uptime monitoring answers three critical questions: ``` -## Key Concepts +## Key concepts - **Downtime**: The period when a service is unavailable or not functioning as expected. It can be caused by server failures, network issues, software bugs, or even cyberattacks. @@ -68,15 +68,13 @@ These terms appear throughout the docs. We use them with specific meanings: - **Region**: A geographic location where openstatus runs checks from (e.g. `iad`, `fra`, `sin`). The terms *region*, *location*, and *probe* are used interchangeably in product UI and prose, but they refer to the same concept: where the request originates. See the [Location Reference](/docs/reference/location) for the full list. - **Private location**: A region you operate yourself — typically a Docker container behind your firewall — so openstatus can check internal services it could not otherwise reach. -## Why Uptime Monitoring is Crucial +## Why uptime monitoring is crucial -- **Business Continuity**: Downtime can lead to significant financial losses, damage to reputation, and loss of customer trust. Uptime monitoring helps you address issues quickly, ensuring your services are always available to your users. +- **Business continuity** — downtime can lead to significant financial losses, damage to reputation, and loss of customer trust. Uptime monitoring helps you address issues quickly, ensuring your services are always available to your users. +- **Performance insight** — monitoring tools often provide data on latency and response times, giving you insights into your service's performance beyond just availability. This can help you optimise your infrastructure and user experience. +- **Proactive problem solving** — instead of waiting for a customer to report an issue, uptime monitoring lets you be the first to know about it. This enables you to troubleshoot and resolve problems before they escalate. -- **Performance Insight**: Monitoring tools often provide data on latency and response times, giving you insights into your service's performance beyond just availability. This can help you optimize your infrastructure and user experience. - -- **Proactive Problem Solving**: Instead of waiting for a customer to report an issue, uptime monitoring allows you to be the first to know about it. This enables you to troubleshoot and resolve problems before they escalate. - -## How it Works +## How it works Uptime monitoring typically involves a monitoring agent that periodically sends a request (like an HTTP GET request) to your service. @@ -93,25 +91,20 @@ Common types of checks include: -## Planning an Uptime Monitoring System +## Planning an uptime monitoring system When planning your own uptime monitoring system, consider the following: -1. Define What to Monitor: Identify all critical services, websites, APIs, and servers that need to be monitored. Prioritize based on business impact. - -2. Select a Monitoring Tool: Choose a tool that fits your needs. Options range from simple free services to complex enterprise-level platforms. Look for features like: - - - **Multiple locations:** Checks from various geographic regions to ensure global availability. +1. Define what to monitor: identify all critical services, websites, APIs, and servers that need to be monitored. Prioritise based on business impact. +2. Select a monitoring tool: choose a tool that fits your needs. Options range from simple free services to complex enterprise-level platforms. Look for features like: - - **Customizable alerting:** Set up different alert thresholds and notification methods. + - **Multiple locations:** checks from various geographic regions to ensure global availability. + - **Customisable alerting:** set up different alert thresholds and notification methods. + - **Reporting and dashboards:** visualise uptime history, performance metrics, and incident reports. + - **Integrations:** connect with your existing tools like Slack, PagerDuty, or email. - - **Reporting and dashboards:** Visualize uptime history, performance metrics, and incident reports. - - - **Integrations:** Connect with your existing tools like Slack, PagerDuty, or email. - -3. **Establish Alerting Rules:** Determine who should be notified and when. Set up an escalation policy, for example, if a primary on-call engineer doesn't respond within 15 minutes, the alert is sent to a manager. - -4. **Regularly Review and Optimize:** Monitor your monitoring system itself. Review historical data to identify recurring issues, fine-tune alert thresholds, and update your list of monitored services as your infrastructure evolves. +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 optimise:** 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 @@ -136,16 +129,14 @@ openstatus supports all these approaches, letting you choose what works best for 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. +- **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](/docs/tutorial/create-your-first-monitor)** - Apply these concepts in practice -- **[Learn about uptime calculations](/docs/concept/uptime-calculation-and-values)** - Understand how uptime percentages work -- **[Building Trust with Status Pages](/docs/concept/best-practices-status-page)** - Communicate effectively during incidents -- **[Monitoring as Code](/docs/concept/uptime-monitoring-as-code)** - Manage monitoring configuration programmatically +- **[Get started with a monitor](/docs/tutorial/create-your-first-monitor)** — apply these concepts in practice. +- **[Learn about uptime calculations](/docs/concept/uptime-calculation-and-values)** — understand how uptime percentages work. +- **[Building trust with status pages](/docs/concept/best-practices-status-page)** — communicate effectively during incidents. +- **[Monitoring as code](/docs/concept/uptime-monitoring-as-code)** — manage monitoring configuration programmatically. diff --git a/apps/web/src/content/pages/docs/guides/getting-started.mdx b/apps/web/src/content/pages/docs/guides/getting-started.mdx index a597e57b..27510095 100644 --- a/apps/web/src/content/pages/docs/guides/getting-started.mdx +++ b/apps/web/src/content/pages/docs/guides/getting-started.mdx @@ -7,41 +7,30 @@ sidebar: order: 1 --- -## 🛠️ How-to Guides +Our how-to guides solve specific problems with step-by-step instructions, walk you through advanced features and integrations, and show you how to customise and extend your openstatus setup. -### What you'll find here +### Monitoring and integration -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 +- **[Monitor your MCP server](/docs/guides/how-to-monitor-mcp-server)** — set up monitoring for Model Context Protocol servers. +- **[Export metrics to an OTLP endpoint](/docs/guides/how-to-export-metrics-to-otlp-endpoint)** — send monitoring data to your observability platform. +- **[Run synthetic tests in GitHub Actions](/docs/guides/how-to-run-synthetic-test-github-action)** — automate testing in your CI/CD pipeline. -### Monitoring & Integration +### Status pages and widgets -Extend your monitoring capabilities: +- **[Add an SVG status badge to a GitHub README](/docs/guides/how-to-add-svg-status-badge)** — display real-time status in your repository. +- **[Use the React status widget](/docs/guides/how-to-use-react-widget)** — embed live status updates in your React application. +- **[Embed a status page in an iframe](/docs/guides/how-to-embed-status-page-iframe)** — drop a chromeless status page into any site. +- **[Deploy a status page on Cloudflare Pages](/docs/guides/how-deploy-status-page-cf-pages)** — host your status page on Cloudflare's edge network. -- **[Monitor Your MCP Server](/docs/guides/how-to-monitor-mcp-server)** - Set up monitoring for Model Context Protocol servers -- **[Export Metrics to OTLP Endpoint](/docs/guides/how-to-export-metrics-to-otlp-endpoint)** - Send monitoring data to your observability platform -- **[Run Synthetic Tests in GitHub Actions](/docs/guides/how-to-run-synthetic-test-github-action)** - Automate testing in your CI/CD pipeline +### Infrastructure and deployment -### Status Pages & Widgets - -Share your status with users: - -- **[Add SVG Status Badge to GitHub README](/docs/guides/how-to-add-svg-status-badge)** - Display real-time status in your repository -- **[Use React Status Widget](/docs/guides/how-to-use-react-widget)** - Embed live status updates in your React application -- **[Deploy Status Page on Cloudflare Pages](/docs/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](/docs/guides/how-to-deploy-probes-cloudflare-containers)** - Run monitoring agents in your own infrastructure -- **[Self-Host openstatus](/docs/guides/self-hosting-openstatus)** - Deploy openstatus on your own servers -- **[Self-Host Status Page Only](/docs/guides/self-host-status-page-only)** - Deploy only the status page without monitoring +- **[Create a private location](/docs/guides/how-to-create-private-location)** — run a monitoring probe on your own infrastructure. +- **[Deploy a private probe on Cloudflare Containers](/docs/guides/how-to-deploy-probes-cloudflare-containers)** — serverless deployment for private probes. +- **[Self-host openstatus](/docs/guides/self-hosting-openstatus)** — deploy openstatus on your own servers. +- **[Self-host the status page only](/docs/guides/self-host-status-page-only)** — deploy just the status page without monitoring. ### Related sections -- **[Tutorials](/docs/tutorial/getting-started)** - If you need step-by-step learning instead -- **[Explanations](/docs/concept/getting-started)** - To understand the concepts behind these guides -- **[Reference](/docs/reference)** - For detailed technical specifications +- **[Tutorials](/docs/tutorial/getting-started)** — for step-by-step learning instead. +- **[Explanations](/docs/concept/getting-started)** — to understand the concepts behind these guides. +- **[Reference](/docs/reference/overview)** — for detailed technical specifications. diff --git a/apps/web/src/content/pages/docs/guides/how-deploy-status-page-cf-pages.mdx b/apps/web/src/content/pages/docs/guides/how-deploy-status-page-cf-pages.mdx index 3de07b31..c1d38654 100644 --- a/apps/web/src/content/pages/docs/guides/how-deploy-status-page-cf-pages.mdx +++ b/apps/web/src/content/pages/docs/guides/how-deploy-status-page-cf-pages.mdx @@ -32,9 +32,9 @@ The code for the template is available on [GitHub](https://github.com/openstatus First, you need an API key to fetch your monitoring data. -1. Navigate to your openstatus dashboard. -2. Go to **Settings** → **API Token**. -3. Click **Create API Key** and copy the key. +1. Navigate to your openstatus dashboard. +2. Go to **Settings** → **API Tokens**. +3. Click **Create API Key** and copy the key. ### 2. Set up the Astro project @@ -50,22 +50,22 @@ pnpm install You need to specify which monitors to display on your page. -1. Open the `src/pages/index.astro` file. -2. Find the following line of code: +1. Open the `src/pages/index.astro` file. +2. Find the following line of code: ```javascript const monitorIds = [1] ``` -3. Replace the `1` with the ID of the monitor you want to display. You can find the monitor ID in the URL when you view a monitor in the openstatus dashboard (`/monitors/[ID]`). You can also add multiple IDs: `[1, 2, 5]`. +3. Replace the `1` with the ID of the monitor you want to display. You can find the monitor ID in the URL when you view a monitor in the openstatus dashboard (`/monitors/[ID]`). You can also add multiple IDs: `[1, 2, 5]`. ### 4. Configure your Cloudflare environment variable Before deploying, you must provide your openstatus API key to Cloudflare. -1. Go to your Cloudflare dashboard and click on **Workers & Pages**. -2. Select your site and go to the **Settings** tab. -3. Navigate to **Environment variables** and add a new variable: - - **Variable name**: `API_KEY` - - **Value**: Paste your openstatus API key here. +1. Go to your Cloudflare dashboard and click on **Workers & Pages**. +2. Select your site and go to the **Settings** tab. +3. Navigate to **Environment variables** and add a new variable: + - **Variable name** — `API_KEY`. + - **Value** — paste your openstatus API key here. ### 5. Deploy to Cloudflare Pages @@ -75,4 +75,4 @@ Now you can deploy your status page. pnpm run pages:deploy ``` -After the command completes, your status page will be live on Cloudflare Pages. 🎉 +After the command completes, your status page will be live on Cloudflare Pages. diff --git a/apps/web/src/content/pages/docs/guides/how-to-add-svg-status-badge.mdx b/apps/web/src/content/pages/docs/guides/how-to-add-svg-status-badge.mdx index de8d8888..0171849d 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-add-svg-status-badge.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-add-svg-status-badge.mdx @@ -19,20 +19,20 @@ openstatus provides embeddable status badges that you can add to any Markdown fi ## Step-by-step guide -### Step 1: Choose your badge type +### Step 1: choose your badge type -We recommend using the modern SVG badge (v2) as it offers more customization options. +We recommend using the modern SVG badge (v2) as it offers more customisation options. -- **SVG Badge (v2)**: More flexible, better styling, and uses a monospaced font. -- **PNG Badge (Legacy)**: Simpler, but with fewer customization options. +- **SVG badge (v2)** — more flexible, better styling, and uses a monospaced font. +- **PNG badge (legacy)** — simpler, but with fewer customisation options. -### Step 2: Add the badge to your README +### Step 2: add the badge to your README Copy the Markdown snippet for your chosen badge type and paste it into your `README.md` file. **Remember to replace `[slug]` with your status page slug.** --- -#### Option A: Modern SVG Badge (Recommended) +#### Option A: modern SVG badge (recommended) This is the recommended badge for most use cases. @@ -42,7 +42,7 @@ This is the recommended badge for most use cases. https://[slug].openstatus.dev/badge/v2 ``` -##### Markdown Snippet +##### Markdown snippet ``` ![Status](https://[slug].openstatus.dev/badge/v2) @@ -52,13 +52,13 @@ https://[slug].openstatus.dev/badge/v2 ![Status](https://status.openstatus.dev/badge/v2) -##### Customization +##### Customisation -You can customize the badge by adding query parameters to the URL. +You can customise the badge by adding query parameters to the URL. -- **Theme**: `?theme=dark` (default is `light`) -- **Size**: `?size=md` (options: `sm`, `md`, `lg`, `xl`; default is `sm`) -- **Variant**: `?variant=outline` (adds a border; default has no border) +- **Theme** — `?theme=dark` (default is `light`). +- **Size** — `?size=md` (options: `sm`, `md`, `lg`, `xl`; default is `sm`). +- **Variant** — `?variant=outline` (adds a border; default has no border). **Example with all options:** @@ -68,7 +68,7 @@ You can customize the badge by adding query parameters to the URL. --- -#### Option B: Legacy PNG Badge +#### Option B: legacy PNG badge Use this badge if you prefer the older style. @@ -78,7 +78,7 @@ Use this badge if you prefer the older style. https://[slug].openstatus.dev/badge ``` -##### Markdown Snippet +##### Markdown snippet ```markdown ![Status](https://[slug].openstatus.dev/badge) @@ -88,10 +88,10 @@ https://[slug].openstatus.dev/badge ![Status](https://status.openstatus.dev/badge) -##### Customization +##### Customisation -- **Theme**: `?theme=dark` (default is `light`) -- **Size**: `?size=lg` (options: `sm`, `md`, `lg`, `xl`; default is `sm`) +- **Theme** — `?theme=dark` (default is `light`). +- **Size** — `?size=lg` (options: `sm`, `md`, `lg`, `xl`; default is `sm`). **Example with all options:** @@ -99,6 +99,6 @@ https://[slug].openstatus.dev/badge ![Status](https://[slug].openstatus.dev/badge?theme=dark&size=lg) ``` -### Step 3: Commit your changes +### Step 3: commit your changes Save your `README.md` file and commit it to your repository. The status badge will now be visible to anyone visiting your repository. It will automatically update to reflect the current status of your services. diff --git a/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx b/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx index 3d0ec4f4..e50760c9 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-configure-status-page.mdx @@ -6,37 +6,22 @@ description: "A step-by-step tutorial to customize and configure your status pag -## What you'll learn +| | | +|---|---| +| **Prerequisites** | openstatus account, a status page (see [Create a status page](/docs/tutorial/create-your-first-status-page)), at least one monitor added to it | -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. +In this guide, you'll customise your status page's appearance and behaviour. You'll explore different display options, themes, and configuration settings to create a status page that matches your brand and communication style. -### Prerequisites +## Status page customisation -- An openstatus account -- A status page already created (see [Create a Status Page](/docs/tutorial/create-your-first-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 -- Multi-language support with a locale switcher -- Preview and live configuration experience - -## Status Page Customization - -openstatus offers enhanced status page customization with multiple themes and display options. - -Explore available themes: [https://themes.openstatus.dev](https://themes.openstatus.dev) +openstatus offers enhanced status page customisation with multiple themes and display options. Explore available themes at [themes.openstatus.dev](https://themes.openstatus.dev). ## Get started Go to the **Status Page Redesign** section in your status page settings and toggle `Enable New Version`. Once enabled, you'll see three subsections: -1. **Tracker Configuration** -2. **Theme Explorer** +1. **Tracker configuration** +2. **Theme explorer** 3. **Links** Once enabled, the subdomain will have a rewrite to the new project. We are adding a `maxAge: 600` request cookie to improve the page load. **If you decide to deactivate the new version, it might take up to 10 minutes for the user to see the old page.** -### 1. Tracker Configuration +### 1. Tracker configuration -We have three new status tracker configurations to provide you with a maximum choice of displaying the collected data. +Three status tracker configurations give you flexibility in how collected data is displayed. -**Bar Type**: How every 'day' is displayed in for a status tracker. Either **absolute** or **manual**. +**Bar type** — how every day is displayed in a status tracker. Either **absolute** or **manual**. -**Card Type**: The card type is only configurable if the bar type is **absolute**. You'll then be able to choose between **duration**, which will show the duration of "success", "error", "degraded" or "maintenance" reports or **requests** where we will share the number of request status itself. If **manual** bar type is chosen, we will only show the most significant status of the day. +**Card type** — only configurable if the bar type is **absolute**. Choose between **duration**, which shows the duration of "success", "error", "degraded", or "maintenance" reports, or **requests**, which shares the number of request statuses themselves. If **manual** bar type is chosen, only the most significant status of the day is shown. -**Show Uptime**: The uptime is calculated by either the **duration** of the different reports _or_ the **request** values depending on what you've chosen for the **absolute** value (incl. incidents). If you've chosen **manual**, it only gets calculated by the duration of your status reports. +**Show uptime** — uptime is calculated by either the **duration** of the different reports _or_ the **request** values depending on what you've chosen for the **absolute** value (including incidents). If you've chosen **manual**, it's calculated only from the duration of your status reports. A few examples to understand it: @@ -91,30 +76,30 @@ Example of **manual bar** with **simple card** and **hiding uptime** alt="manual bar type and hiding uptime" /> -### 2. Theme Explorer +### 2. Theme explorer -You can choose between different themes. We start with the following three: +You can choose between different themes. The starting set is: - `default` (openstatus) - `supabase` - `github-high-contrast` -Visit [themes.openstatus.dev](https://themes.openstatus.dev) to see the list of supported themes. If you want, you can contribute your own to the list. +Visit [themes.openstatus.dev](https://themes.openstatus.dev) to see the list of supported themes. You can also contribute your own. -If you use AI agents, install the [`openstatus-theme` skill](https://github.com/openstatusHQ/skills/tree/main/skills/openstatus-theme) with `npx skills add openstatushq/skills --skill openstatus-theme` to get guided help through palette design, accessibility checks, file scaffolding, and PR submission. +If you use AI agents, install the [`openstatus-theme` skill](https://github.com/openstatusHQ/skills/tree/main/skills/openstatus-theme) with `npx skills add openstatushq/skills --skill openstatus-theme` for guided help through palette design, accessibility checks, file scaffolding, and PR submission. ### 3. Links -Let's have a closer look at your status page header navigation: +Your status page header navigation: Header navigation of your status page -**Homepage URL**: Your logo will support linking to your own website. +**Homepage URL** — your logo will link to your own website. -**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:support@openstatus.dev`). +**Contact URL** — if filled out, users will see a `Message` icon they can click to reach a contact page. This can also be an email client by starting the input with `mailto:` (e.g. `mailto:support@openstatus.dev`). --- @@ -122,11 +107,11 @@ Let's have a closer look at your status page header navigation: You can offer your status page in multiple languages. In the **Locales** section of your status page settings: -1. Choose a **Default Locale** — the fallback language for visitors. -2. Enable the **Locale Switcher** to let visitors pick their preferred language. +1. Choose a **default locale** — the fallback language for visitors. +2. Enable the **locale switcher** to let visitors pick their preferred language. 3. Select which languages to make available. -Currently supported: English, French, and German. See [How to translate your status page](/docs/guides/how-to-translate-status-page) for details on contributing new translations. +See [How to translate your status page](/docs/guides/how-to-translate-status-page) for the supported list and how to contribute new translations. --- @@ -134,28 +119,24 @@ We are continuously adding new 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 -- ✅ Customized status tracker display options -- ✅ Explored and applied theme settings -- ✅ Added navigation links to your status page -- ✅ Configured locales and the language switcher -- ✅ Previewed changes before making them live - -## What's next? +- Enabled and configured the new status page design +- Customised status tracker display options +- Explored and applied theme settings +- Added navigation links to your status page +- Configured locales and the language switcher +- Previewed changes before making them live -Now that your status page is configured, you can: +## What's next -- **[Building Trust with Status Pages](/docs/concept/best-practices-status-page)** - Learn effective incident communication -- **[Add Status Subscribers](/docs/reference/subscriber)** - Let users subscribe to updates +- **[Building trust with status pages](/docs/concept/best-practices-status-page)** — learn effective incident communication. +- **[Status subscribers](/docs/reference/subscriber)** — let users subscribe to updates. ### Learn more -- **[Status Page Reference](/docs/reference/status-page)** - Complete configuration options -- **[Uptime Calculation Values](/docs/concept/uptime-calculation-and-values)** - How uptime percentages work - +- **[Status page reference](/docs/reference/status-page)** — complete configuration options. +- **[Uptime calculation values](/docs/concept/uptime-calculation-and-values)** — how uptime percentages work. -## Video Tutorial +## Video tutorial Private locations are currently in **beta**. Some features like incident creation and public status page support are not yet available for private locations. -## What are private locations? - -Private locations allow you to monitor internal applications from within your own infrastructure, rather than solely relying on our public cloud-based regions. By deploying monitoring probes as Docker containers on your own machines, you can: +For background on when to use a private location and how the connection works, see [Understanding private locations](/docs/concept/private-locations). -- Monitor internal APIs and services behind your firewall -- Get detailed timing and latency data from your specific deployment location -- Monitor from on-prem servers, Raspberry Pi devices, or any Docker-capable machine - -## Step 1: Create a private location +## Step 1: create a private location 1. Navigate to **Settings** > **Private Locations** in your openstatus dashboard 2. Click **Create Private Location** @@ -49,7 +28,7 @@ After creation, you'll receive a **token**. Copy this token — you'll need it i -## Step 2: Deploy the Docker probe +## Step 2: deploy the Docker probe Run the monitoring probe on your server using Docker: @@ -76,7 +55,7 @@ CONTAINER ID IMAGE STATUS NAMES abc123 ghcr.io/openstatushq/probe:latest Up 2 minutes openstatus-probe ``` -## Step 3: Assign monitors to your private location +## Step 3: assign monitors to your private location 1. Go to **Settings** > **Private Locations** and select your location 2. Choose which monitors should run from this private location @@ -86,10 +65,9 @@ abc123 ghcr.io/openstatushq/probe:latest Up 2 minutes openstatus-prob ## What you've accomplished -You've successfully: -- ✅ Created a private location in openstatus -- ✅ Deployed a monitoring probe on your own infrastructure -- ✅ Assigned monitors to check from your private location +- Created a private location in openstatus +- Deployed a monitoring probe on your own infrastructure +- Assigned monitors to check from your private location ## Current limitations @@ -107,8 +85,9 @@ docker logs openstatus-probe ``` Common causes: -- **Invalid token:** Double-check the token value — ensure no extra spaces or newlines -- **Network issues:** Ensure the container can reach `api.openstatus.dev` on port 443 + +- **Invalid token** — double-check the token value; ensure no extra spaces or newlines. +- **Network issues** — ensure the container can reach `api.openstatus.dev` on port 443. ### No data appearing in the dashboard @@ -129,7 +108,7 @@ docker run -d \ ghcr.io/openstatushq/probe:latest ``` -## What's next? +## What's next -- **[Read our Raspberry Pi deployment guide](https://www.openstatus.dev/blog/deploy-private-locations-raspberry-pi)** — Deploy probes on low-cost hardware -- **[Create a Monitor](/docs/tutorial/create-your-first-monitor)** — Set up more monitors to run from your private location +- **[Read our Raspberry Pi deployment guide](https://www.openstatus.dev/blog/deploy-private-locations-raspberry-pi)** — deploy probes on low-cost hardware. +- **[Create a monitor](/docs/tutorial/create-your-first-monitor)** — set up more monitors to run from your private location. diff --git a/apps/web/src/content/pages/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx b/apps/web/src/content/pages/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx index e44815d8..f02981d3 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-deploy-probes-cloudflare-containers.mdx @@ -28,12 +28,12 @@ The code for the Cloudflare Worker template is available on [GitHub](https://git First, you need to create a private location in your openstatus workspace to get an access key. -1. Go to the openstatus dashboard. -2. Navigate to **Settings** > **Private Locations**. -3. Click **Create Private Location**. -4. Give it a human-readable name (e.g., "Cloudflare-EU"). -5. Copy the generated token and save it somewhere secure. -6. Click **Submit** to save the new private location. +1. Go to the openstatus dashboard. +2. Navigate to **Settings** > **Private Locations**. +3. Click **Create Private Location**. +4. Give it a human-readable name (e.g., "Cloudflare-EU"). +5. Copy the generated token and save it somewhere secure. +6. Click **Submit** to save the new private location. ### 2. Set up the Cloudflare project @@ -67,13 +67,13 @@ pnpm wrangler containers push openstatus-private-location:v1 Now, configure your Cloudflare project to use the container and run it on a schedule. -1. Open the `wrangler.toml` file. -2. Add a `[containers]` section to link the image you pushed. Replace `GENERATED_ID` with the actual ID from the previous step's output. +1. Open the `wrangler.toml` file. +2. Add a `[containers]` section to link the image you pushed. Replace `GENERATED_ID` with the actual ID from the previous step's output. ```toml [containers] image = "registry.cloudflare.com/GENERATED_ID/openstatus-private-location:v1" ``` -3. Add a `triggers` section to run the worker on a cron schedule. This keeps the container alive, as Cloudflare Containers automatically scales to zero. +3. Add a `triggers` section to run the worker on a cron schedule. This keeps the container alive, as Cloudflare Containers automatically scales to zero. ```toml triggers = { cron = ["*/2 * * * *"] } # Runs every 2 minutes ``` @@ -82,11 +82,11 @@ Now, configure your Cloudflare project to use the container and run it on a sche Update the worker script (`index.ts`) to start the container with the correct environment variables. -1. Set the `sleepAfter` value to control how long the container runs after being invoked. +1. Set the `sleepAfter` value to control how long the container runs after being invoked. ```typescript sleepAfter = "150s"; ``` -2. Update the `scheduled` function to pass your openstatus key to the container. +2. Update the `scheduled` function to pass your openstatus key to the container. ```typescript async scheduled(_controller: any, env: Env) { try { diff --git a/apps/web/src/content/pages/docs/guides/how-to-embed-status-page-iframe.mdx b/apps/web/src/content/pages/docs/guides/how-to-embed-status-page-iframe.mdx index 9a18dbd7..29f20b97 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-embed-status-page-iframe.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-embed-status-page-iframe.mdx @@ -77,8 +77,8 @@ Show components in forced dark theme: ## Notes and caveats -- **Height:** iframes do not auto-size to their content. Set a `height` attribute appropriate for the sections you enabled. +- **Height** — iframes do not auto-size to their content. Set a `height` attribute appropriate for the sections you enabled. - **Internal links** (e.g. clicking an incident banner) open in a new tab when embedded, so your site's iframe stays put. - **Password-protected status pages** may not authenticate correctly inside iframes due to browser third-party cookie restrictions (Safari ITP, Chrome). Visitors may need to authenticate on the full status page first. -- **Attribution:** non-whitelabel pages show a centered "powered by openstatus.dev" link in the embed footer. Whitelabel pages hide the footer entirely. -- **Sandboxed iframes** must include at least `allow-scripts allow-same-origin` for the status page to run, plus `allow-popups` for the "open in new tab" behavior on internal links. +- **Attribution** — non-whitelabel pages show a centred "powered by openstatus.dev" link in the embed footer. Whitelabel pages hide the footer entirely. +- **Sandboxed iframes** must include at least `allow-scripts allow-same-origin` for the status page to run, plus `allow-popups` for the "open in new tab" behaviour on internal links. diff --git a/apps/web/src/content/pages/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx b/apps/web/src/content/pages/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx index 6e2c8361..3b1e9bad 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-export-metrics-to-otlp-endpoint.mdx @@ -23,10 +23,10 @@ openstatus can export monitoring metrics to any OTLP (OpenTelemetry Protocol) co ### 1. Locate your OTLP endpoint URL and headers -First, you need to find the specific URL and any required authentication headers from your observability platform. This is usually found in the documentation under "OTLP," "OpenTelemetry," or "Metrics Export." +First, you need to find the specific URL and any required authentication headers from your observability platform. This is usually found in the documentation under "OTLP", "OpenTelemetry", or "Metrics Export". -- **Endpoint URL**: Look for an HTTP endpoint for OTLP metrics. It will typically end in `/v1/metrics`. For example: `https://otlp.your-provider.com/v1/metrics`. -- **Headers**: You will likely need an authentication header, such as `Authorization: Bearer YOUR_API_KEY` or `X-API-Key: YOUR_API_KEY`. +- **Endpoint URL** — look for an HTTP endpoint for OTLP metrics. It typically ends in `/v1/metrics`. For example: `https://otlp.your-provider.com/v1/metrics`. +- **Headers** — you will likely need an authentication header, such as `Authorization: Bearer YOUR_API_KEY` or `X-API-Key: YOUR_API_KEY`. ### 2. Configure your `openstatus.yaml` file diff --git a/apps/web/src/content/pages/docs/guides/how-to-import-status-page.mdx b/apps/web/src/content/pages/docs/guides/how-to-import-status-page.mdx index 2eef0bc1..cae38fa8 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-import-status-page.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-import-status-page.mdx @@ -5,23 +5,21 @@ description: "Import your existing status page setup from Atlassian Statuspage, --- -## What you'll learn - | | | |---|---| | **Time** | ~2 minutes | | **Level** | Beginner | | **Prerequisites** | openstatus account | -Migrating away from your current status page provider does not have to mean starting from scratch. openstatus can import your existing status page configuration -- including components, incidents, maintenances, and subscribers -- directly from another provider. This tutorial walks through the provider-agnostic import flow step by step. +Migrating away from your current status page provider does not have to mean starting from scratch. openstatus can import your existing status page configuration — including components, incidents, maintenances, and subscribers — directly from another provider. This guide walks through the provider-agnostic import flow step by step. ## Supported providers openstatus currently supports importing from three providers: -- **[Atlassian Statuspage](https://openstatus.dev/guides/migrate-from-atlassian-statuspage)** -- The most widely used hosted status page solution. -- **[Better Stack](https://openstatus.dev/guides/migrate-from-betterstack)** -- Monitoring and status page platform (formerly Better Uptime). -- **[Instatus](https://openstatus.dev/guides/migrate-from-instatus)** -- A modern status page service with component-level tracking. +- **[Atlassian Statuspage](https://openstatus.dev/guides/migrate-from-atlassian-statuspage)** — the most widely used hosted status page solution. +- **[Better Stack](https://openstatus.dev/guides/migrate-from-betterstack)** — monitoring and status page platform (formerly Better Uptime). +- **[Instatus](https://openstatus.dev/guides/migrate-from-instatus)** — a modern status page service with component-level tracking. Each link above points to a provider-specific migration guide with detailed instructions on API key generation and data mapping. @@ -33,14 +31,14 @@ You need a read-access API key from your current provider. The key is used only ### 2. Open the import page -In the openstatus dashboard, navigate to **Status Pages** and select the status page you want to import into. If you have not yet created a status page, create one first -- see [Create a Status Page](/docs/tutorial/create-your-first-status-page) for instructions. +In the openstatus dashboard, navigate to **Status Pages** and select the status page you want to import into. If you have not yet created a status page, create one first — see [Create a status page](/docs/tutorial/create-your-first-status-page) for instructions. Open the **Components** tab and scroll down to the **Import** section at the bottom of the page. @@ -51,13 +49,13 @@ Choose your source provider from the dropdown and paste your API key. Depending ### 4. Preview the import -After submitting your credentials, the importer fetches your existing data and displays a preview summary. No data is written at this stage -- the preview is read-only. +After submitting your credentials, the importer fetches your existing data and displays a preview summary. No data is written at this stage — the preview is read-only. The preview includes: -- **Resource counts** -- Number of components, component groups, incidents, maintenances, and subscribers that will be imported. -- **Warnings** -- Any resources that cannot be imported or require manual attention (for example, unsupported subscriber types or resources that exceed your plan limits). -- **Mapping details** -- How source resources map to openstatus equivalents. +- **Resource counts** — number of components, component groups, incidents, maintenances, and subscribers that will be imported. +- **Warnings** — any resources that cannot be imported or require manual attention (for example, unsupported subscriber types or resources that exceed your plan limits). +- **Mapping details** — how source resources map to openstatus equivalents. Review the summary carefully before proceeding. If the counts do not match what you expect, verify that your API key has sufficient permissions to read all resources. @@ -74,11 +72,11 @@ Importing incidents and maintenances creates historical records in openstatus. T Click **Import** to start the process. The import runs in phases: -1. **Components and groups** -- Structural elements are created first so that incidents and maintenances can reference them. -2. **Incidents** -- Historical and active incidents, including updates and component impact. -3. **Maintenances** -- Scheduled and completed maintenance windows. -4. **Subscribers** -- Email subscribers (where supported by the source provider). -5. **Monitors** -- Existing monitoring checks (Better Stack only). +1. **Components and groups** — structural elements are created first so that incidents and maintenances can reference them. +2. **Incidents** — historical and active incidents, including updates and component impact. +3. **Maintenances** — scheduled and completed maintenance windows. +4. **Subscribers** — email subscribers (where supported by the source provider). +5. **Monitors** — existing monitoring checks (Better Stack only). A progress indicator shows the current phase and any errors encountered. When the import finishes, you are redirected to your status page configuration with all imported data in place. @@ -105,15 +103,12 @@ For a detailed breakdown of how each resource type is mapped, see the provider-s ## After import -The import creates resources in openstatus but does not automatically make your status page live or redirect traffic. Complete the following steps to finalize your migration: - -1. **Verify imported data.** Open your status page and confirm that components, incidents, and maintenances appear correctly. Check that component groups are structured as expected. - -2. **Connect monitors to static components.** Imported components may not have monitors attached. Navigate to each component and link an existing openstatus monitor, or [create a new monitor](/docs/tutorial/create-your-first-monitor) for it. +The import creates resources in openstatus but does not automatically make your status page live or redirect traffic. Complete the following steps to finalise your migration: -3. **Update DNS for your custom domain.** If you are migrating a custom domain (e.g., `status.yourdomain.com`), update your CNAME record to point to `status.openstatus.dev`. See the [Status Page Reference](/docs/reference/status-page) for DNS configuration details. - -4. **Invite subscribers.** If your provider does not support subscriber export (Better Stack) or you need to re-verify email subscribers, use the openstatus subscription system to notify your users of the new page. +1. **Verify imported data** — open your status page and confirm that components, incidents, and maintenances appear correctly. Check that component groups are structured as expected. +2. **Connect monitors to static components** — imported components may not have monitors attached. Navigate to each component and link an existing openstatus monitor, or [create a new monitor](/docs/tutorial/create-your-first-monitor) for it. +3. **Update DNS for your custom domain** — if you are migrating a custom domain (e.g., `status.yourdomain.com`), update your CNAME record to point to `status.openstatus.dev`. See the [status page reference](/docs/reference/status-page) for DNS configuration details. +4. **Invite subscribers** — if your provider does not support subscriber export (Better Stack) or you need to re-verify email subscribers, use the openstatus subscription system to notify your users of the new page. ## Troubleshooting @@ -137,14 +132,12 @@ If a partial import leaves your status page in an inconsistent state, you can de Running the import a second time does not deduplicate incidents or maintenances. If you need to re-import, delete the previously imported records first to avoid duplicate entries appearing on your status page. -## What's next? - -Now that your data is in openstatus, explore these resources to get the most out of your new setup: +## What's next -- **[Configure Your Status Page](/docs/guides/how-to-configure-status-page)** -- Customize the appearance, add a logo, and configure notification preferences. -- **[Create Your First Monitor](/docs/tutorial/create-your-first-monitor)** -- Set up synthetic monitoring for your imported components. -- **[Status Page Reference](/docs/reference/status-page)** -- Full reference for all status page configuration options. -- **[Building Trust with Status Pages](/docs/concept/best-practices-status-page)** -- Best practices for transparent incident communication. +- **[Configure your status page](/docs/guides/how-to-configure-status-page)** — customise the appearance, add a logo, and configure notification preferences. +- **[Create your first monitor](/docs/tutorial/create-your-first-monitor)** — set up synthetic monitoring for your imported components. +- **[Status page reference](/docs/reference/status-page)** — full reference for all status page configuration options. +- **[Building trust with status pages](/docs/concept/best-practices-status-page)** — best practices for transparent incident communication. ### Provider-specific guides diff --git a/apps/web/src/content/pages/docs/guides/how-to-manage-openstatus-with-terraform-cli.mdx b/apps/web/src/content/pages/docs/guides/how-to-manage-openstatus-with-terraform-cli.mdx index 0d00b385..fd94ff30 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-manage-openstatus-with-terraform-cli.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-manage-openstatus-with-terraform-cli.mdx @@ -5,37 +5,22 @@ description: "Use Terraform to manage monitors, status pages, and notifications --- -## What you'll learn - | | | |---|---| | **Time** | ~20 minutes | | **Level** | Intermediate | -| **Prerequisites** | openstatus account, Terraform installed, CLI installed | +| **Prerequisites** | openstatus account, [Terraform](https://developer.hashicorp.com/terraform/install) installed, [openstatus CLI](/docs/tutorial/get-started-with-openstatus-cli) installed, API token from workspace settings | -In this tutorial, you'll set up a complete monitoring stack using two tools: +In this guide, you'll set up a complete monitoring stack using two tools: - **Terraform** to manage your infrastructure — monitors, status pages, notifications. These are long-lived resources that change infrequently and benefit from code review, version control, and `terraform plan`. - **The openstatus CLI** to handle operational tasks — creating and updating status reports during incidents. These are time-sensitive actions that need to happen fast, often from a terminal or a CI script. -### Prerequisites - -- An openstatus account ([sign up free](https://www.openstatus.dev)) -- [Terraform](https://developer.hashicorp.com/terraform/install) installed -- The openstatus CLI installed ([installation guide](/docs/tutorial/get-started-with-openstatus-cli)) -- Your API token from workspace settings (Settings > API) - -### What you'll build - -By the end of this tutorial, you'll have: -- HTTP, TCP, and DNS monitors deployed via Terraform -- A public status page with grouped components -- Slack notifications wired to your monitors -- A status report workflow using the CLI for incident communication +By the end you'll have HTTP, TCP, and DNS monitors deployed via Terraform, a public status page with grouped components, Slack notifications wired to your monitors, and a status report workflow running through the CLI. -## Part 1 — Infrastructure with Terraform +## Part 1 — infrastructure with Terraform -### Step 1 — Set up the provider +### Step 1 — set up the provider Create a new directory for your Terraform configuration and add a `main.tf` file: @@ -67,7 +52,7 @@ terraform init -### Step 2 — Define your monitors +### Step 2 — define your monitors Add monitors to your `main.tf`. We'll create three types — HTTP, TCP, and DNS. @@ -135,7 +120,7 @@ resource "openstatus_dns_monitor" "domain" { } ``` -### Step 3 — Add notifications +### Step 3 — add notifications Wire up a Slack notification so you get alerted when monitors fail: @@ -161,7 +146,7 @@ resource "openstatus_notification" "slack" { -### Step 4 — Create a status page with components +### Step 4 — create a status page with components Define a public status page and organize monitors into component groups: @@ -205,7 +190,7 @@ resource "openstatus_status_page_component" "db_component" { } ``` -### Step 5 — Plan and apply +### Step 5 — plan and apply Preview the changes Terraform will make: @@ -223,7 +208,7 @@ terraform apply - Open your openstatus dashboard — your monitors should appear in the Monitors tab - Visit your status page at `https://.openstatus.dev` — you should see your component groups and monitors -### Step 6 — Update your infrastructure +### Step 6 — update your infrastructure To make changes, edit your `.tf` files and re-apply. For example, add a new region to the API monitor: @@ -240,7 +225,7 @@ terraform apply # Apply the update Terraform only modifies what changed — the monitor gets updated in place, no downtime. -### Step 7 — Import existing resources +### Step 7 — import existing resources If you already have monitors, status pages, or notifications created in the dashboard, you can generate the corresponding Terraform configuration automatically using the CLI: @@ -260,11 +245,11 @@ terraform import openstatus_notification.slack After importing, run `terraform plan` to ensure your `.tf` files match the imported state. Adjust any drift until the plan shows no changes. -## Part 2 — Status reports with the CLI +## Part 2 — status reports with the CLI Terraform is great for infrastructure, but status reports are operational — you create them when an incident is happening and update them as you investigate and resolve. The CLI is the right tool here. -### Step 8 — Configure the CLI +### Step 8 — configure the CLI Make sure your API token is set: @@ -278,7 +263,7 @@ Verify your setup: openstatus whoami ``` -### Step 9 — Create a status report +### Step 9 — create a status report When an incident starts, create a status report and link it to your status page and affected components: @@ -300,7 +285,7 @@ Key flags: -### Step 10 — Post updates as you investigate +### Step 10 — post updates as you investigate As the incident progresses, add updates to the report. Each update changes the status and adds a timestamped message: @@ -325,7 +310,7 @@ openstatus status-report add-update \ Each update appears on your public status page as a timeline entry, giving your users clear visibility into what happened and when. -### Step 11 — Review and manage reports +### Step 11 — review and manage reports List recent incidents: @@ -388,24 +373,23 @@ Here's how the two tools fit into your workflow: ## What you've accomplished -You've successfully: -- ✅ Deployed HTTP, TCP, and DNS monitors with Terraform -- ✅ Created a status page with component groups and monitor-linked components -- ✅ Configured Slack notifications for monitor failures -- ✅ Used the CLI to manage the full lifecycle of an incident status report -- ✅ Learned when to use Terraform vs. the CLI for different tasks +- Deployed HTTP, TCP, and DNS monitors with Terraform +- Created a status page with component groups and monitor-linked components +- Configured Slack notifications for monitor failures +- Used the CLI to manage the full lifecycle of an incident status report +- Learned when to use Terraform vs. the CLI for different tasks -## What's next? +## What's next -- **[Terraform Provider Reference](/docs/reference/terraform)** — Full specification for all resources and data sources -- **[Run Synthetic Tests in GitHub Actions](/docs/guides/how-to-run-synthetic-test-github-action)** — Automate monitoring in your CI/CD pipeline -- **[Export Metrics to an OTLP Endpoint](/docs/guides/how-to-export-metrics-to-otlp-endpoint)** — Send monitor data to your observability stack +- **[Terraform provider reference](/docs/reference/terraform)** — full specification for all resources and data sources. +- **[Run synthetic tests in GitHub Actions](/docs/guides/how-to-run-synthetic-test-github-action)** — automate monitoring in your CI/CD pipeline. +- **[Export metrics to an OTLP endpoint](/docs/guides/how-to-export-metrics-to-otlp-endpoint)** — send monitor data to your observability stack. -## Learn more +### Learn more -- **[Understanding Monitoring as Code](/docs/concept/uptime-monitoring-as-code)** — Why manage monitors as code -- **[CLI Reference](/docs/reference/cli-reference)** — Complete command documentation -- **[Status Report Reference](/docs/reference/status-report)** — Status report properties and lifecycle -- **[HTTP Monitor Reference](/docs/reference/http-monitor)** — Full HTTP monitor specification -- **[TCP Monitor Reference](/docs/reference/tcp-monitor)** — Full TCP monitor specification -- **[DNS Monitor Reference](/docs/reference/dns-monitor)** — Full DNS monitor specification +- **[Understanding monitoring as code](/docs/concept/uptime-monitoring-as-code)** — why manage monitors as code. +- **[CLI reference](/docs/reference/cli-reference)** — complete command documentation. +- **[Status report reference](/docs/reference/status-report)** — status report properties and lifecycle. +- **[HTTP monitor reference](/docs/reference/http-monitor)** — full HTTP monitor specification. +- **[TCP monitor reference](/docs/reference/tcp-monitor)** — full TCP monitor specification. +- **[DNS monitor reference](/docs/reference/dns-monitor)** — full DNS monitor specification. diff --git a/apps/web/src/content/pages/docs/guides/how-to-monitor-mcp-server.mdx b/apps/web/src/content/pages/docs/guides/how-to-monitor-mcp-server.mdx index 8b0958d7..ca3a684a 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-monitor-mcp-server.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-monitor-mcp-server.mdx @@ -6,28 +6,20 @@ sidebar: label: Monitor your MCP Server --- -## Problem: Ensuring Your MCP Server is Always Responsive +## Problem 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? -## Solution: JSON-RPC Ping Monitoring with openstatus +## Solution -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. +openstatus monitors MCP servers by sending JSON-RPC `ping` requests to your endpoint from multiple global locations. This verifies not only network reachability but also the correct functioning of your server's JSON-RPC interface. This guide walks you through setting up comprehensive monitoring for any MCP server using the openstatus CLI. ## Prerequisites -Before you begin, ensure you have: - -- An [openstatus account](https://www.openstatus.dev/app/login). -- The [openstatus CLI installed](/docs/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). - -## Background: Understanding MCP for Monitoring - -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. - -### The MCP Server and JSON-RPC 2.0 +- An [openstatus account](https://www.openstatus.dev/app/login). +- The [openstatus CLI installed](/docs/tutorial/get-started-with-openstatus-cli). +- An MCP server with a publicly accessible endpoint. +- A basic understanding of the [JSON-RPC 2.0 protocol](https://www.jsonrpc.org/specification). ## Step-by-step guide @@ -72,23 +64,23 @@ mcp-server: ### 2. Understand the configuration -Let's break down the key fields in this YAML configuration: +The key fields in this YAML configuration: -- `name` & `description`: A human-readable name and explanation for your monitor. -- `frequency`: How often openstatus will run the check (e.g., `1m`, `5m`, `10m`). -- `regions`: An array of geographic regions from which to perform checks (e.g., `["iad", "ams", "lax"]`). Monitoring from multiple regions helps detect localized issues. -- `retry`: The number of times to retry a failed check before marking it as down. -- `kind`: Must be `http` for MCP servers. -- `request`: - - `url`: The full URL of your MCP server's JSON-RPC endpoint. - - `method`: Must be `POST` for JSON-RPC requests. - - `body`: The JSON-RPC `ping` request payload. - - `headers`: Standard HTTP headers for JSON-RPC communication. -- `assertions`: Rules to validate the server's response. - - `statusCode`: Ensures the HTTP response is `200 OK`. - - `textBody`: Verifies that the response payload exactly matches the expected JSON-RPC `ping` result. +- `name` and `description` — human-readable name and explanation for your monitor. +- `frequency` — how often openstatus runs the check (e.g., `1m`, `5m`, `10m`). +- `regions` — an array of geographic regions from which to perform checks (e.g., `["iad", "ams", "lax"]`). Monitoring from multiple regions helps detect localised issues. +- `retry` — the number of times to retry a failed check before marking it as down. +- `kind` — must be `http` for MCP servers. +- `request`: + - `url` — the full URL of your MCP server's JSON-RPC endpoint. + - `method` — must be `POST` for JSON-RPC requests. + - `body` — the JSON-RPC `ping` request payload. + - `headers` — standard HTTP headers for JSON-RPC communication. +- `assertions` — rules to validate the server's response. + - `statusCode` — ensures the HTTP response is `200 OK`. + - `textBody` — verifies that the response payload exactly matches the expected JSON-RPC `ping` result. -### 3. Test your MCP server (Optional) +### 3. Test your MCP server (optional) Before deploying your monitor, you can manually test your MCP server's `ping` endpoint with `curl` to confirm it responds as expected. This helps verify the `target` value for your `textBody` assertion. @@ -111,28 +103,21 @@ openstatus create openstatus.yaml This command uploads your configuration, and monitoring will begin immediately. -## Conclusion: Comprehensive MCP Server Monitoring Achieved - -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. - -## What You've Accomplished - -- ✅ 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 +## What you've accomplished -Now that your MCP server is under robust monitoring, consider further enhancing your setup: +- Configured a JSON-RPC based monitor for your MCP server +- Implemented precise assertions to validate `ping` responses +- Set up global monitoring to detect localised or widespread issues +- Automated monitor deployment using a version-controlled YAML configuration +## What's next -- **[Export Metrics to OTLP](/docs/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](/docs/guides/how-to-run-synthetic-test-github-action)**: Incorporate these synthetic checks into your CI/CD pipeline for pre-deployment validation. +- **[Export metrics to OTLP](/docs/guides/how-to-export-metrics-to-otlp-endpoint)** — integrate your MCP monitoring data with your existing observability platform. +- **[Run synthetic tests in GitHub Actions](/docs/guides/how-to-run-synthetic-test-github-action)** — incorporate these synthetic checks into your CI/CD pipeline. -## Related Resources +### Learn more -- **[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](/docs/reference/http-monitor)**: Comprehensive API reference for HTTP monitors. -- **[CLI Reference](/docs/reference/cli-reference)**: Full documentation for the openstatus CLI. +- **[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](/docs/reference/http-monitor)** — comprehensive reference for HTTP monitors. +- **[CLI reference](/docs/reference/cli-reference)** — full documentation for the openstatus CLI. diff --git a/apps/web/src/content/pages/docs/guides/how-to-run-synthetic-test-github-action.mdx b/apps/web/src/content/pages/docs/guides/how-to-run-synthetic-test-github-action.mdx index 18129c3a..c1a981ee 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-run-synthetic-test-github-action.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-run-synthetic-test-github-action.mdx @@ -35,11 +35,12 @@ tests: ``` **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]` -**Tip:** Start with your most critical monitors and expand from there. +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]`. + +**Tip:** start with your most critical monitors and expand from there. ### 2. Get your openstatus API key @@ -98,13 +99,12 @@ 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 +- 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 +## Customisation options ### Run on different branches @@ -142,35 +142,34 @@ on: ## 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 +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 + +- Verify `OPENSTATUS_API_KEY` secret is set correctly. +- Check that your API key hasn't been revoked. **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 +- Confirm monitor IDs are correct in `openstatus.config.yaml`. +- Ensure monitors are active in your openstatus dashboard. -## Next steps +**Tests timing out:** -- **[Monitor Your MCP Server](/docs/guides/how-to-monitor-mcp-server)** - Advanced monitoring examples -- **[Monitoring as Code](/docs/concept/uptime-monitoring-as-code)** - Manage monitors with YAML -- **[CLI Reference](/docs/reference/cli-reference)** - Automate monitor management -- **[Export Metrics](/docs/guides/how-to-export-metrics-to-otlp-endpoint)** - Send data to your observability platform +- Check that your endpoints are accessible from GitHub's runners. +- Consider increasing timeouts in monitor configuration. -## Related resources +## What's next -- **[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 community +- **[Monitor your MCP server](/docs/guides/how-to-monitor-mcp-server)** — advanced monitoring examples. +- **[Monitoring as code](/docs/concept/uptime-monitoring-as-code)** — manage monitors with YAML. +- **[CLI reference](/docs/reference/cli-reference)** — automate monitor management. +- **[Export metrics](/docs/guides/how-to-export-metrics-to-otlp-endpoint)** — send data to your observability platform. +- **[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. diff --git a/apps/web/src/content/pages/docs/guides/how-to-setup-slack-agent.mdx b/apps/web/src/content/pages/docs/guides/how-to-setup-slack-agent.mdx index b230669d..e9655366 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-setup-slack-agent.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-setup-slack-agent.mdx @@ -5,36 +5,23 @@ description: "A step-by-step tutorial to install the openstatus Slack agent and --- -## What you'll learn - | | | |---|---| | **Time** | ~5 minutes | | **Level** | Beginner | -| **Prerequisites** | openstatus account, Slack workspace admin access | +| **Prerequisites** | openstatus account, Slack workspace where you have permission to install apps | -In this tutorial, you'll learn how to install the openstatus Slack agent so you can manage incidents directly from your Slack workspace — no need to switch to the dashboard. The agent uses an LLM to interpret natural-language messages like *"create an incident for the payment API"* and turn them into status page actions. +In this guide, you'll install the openstatus Slack agent so you can manage incidents directly from your Slack workspace — no need to switch to the dashboard. The agent uses an LLM to interpret natural-language messages like *"create an incident for the payment API"* and turn them into status page actions. -### Prerequisites - -- An openstatus account ([openstatus.dev](https://www.openstatus.dev)) -- A Slack workspace where you have permission to install apps - -### What you'll get - -By the end of this tutorial, you'll have: -- The openstatus Slack agent installed in your workspace -- The ability to create, update, and resolve incidents from Slack - -## Install the Slack Agent +## Install the Slack agent -### 1. Go to Settings +### 1. Go to settings Navigate to **Settings** > **Integrations** in your openstatus dashboard. -### 2. Install the Slack Integration +### 2. Install the Slack integration Click the **Install Slack** button. You'll be redirected to Slack's authorization page where you can select the workspace and channel you want to connect. @@ -42,7 +29,7 @@ Grant the requested permissions and click **Allow** to complete the installation -### 3. Verify the Installation +### 3. Verify the installation After completing the OAuth flow, go to the Slack channel you selected and type: @@ -54,7 +41,7 @@ The bot should respond with a summary of your monitors. If you see a response, t -### 4. Start Managing Incidents from Slack +### 4. Start managing incidents from Slack Here are some examples of what you can do: @@ -92,18 +79,17 @@ Plan downtime so subscribers are informed in advance. ## What you've accomplished -Congratulations! You've successfully: -- ✅ Installed the openstatus Slack agent in your workspace -- ✅ Connected your openstatus account to Slack -- ✅ Learned how to manage incidents directly from Slack +- Installed the openstatus Slack agent in your workspace +- Connected your openstatus account to Slack +- Learned how to manage incidents directly from Slack ## Troubleshooting ### The bot doesn't respond when mentioned -1. **Check the channel:** Make sure you're mentioning `@openstatus` in the channel you selected during installation. -2. **Check permissions:** Go to **Settings** > **Integrations** and verify the Slack integration shows as connected. -3. **Reinstall:** If the integration appears disconnected, click **Install Slack** again to re-authorize. +1. **Check the channel** — make sure you're mentioning `@openstatus` in the channel you selected during installation. +2. **Check permissions** — go to **Settings** > **Integrations** and verify the Slack integration shows as connected. +3. **Reinstall** — if the integration appears disconnected, click **Install Slack** again to re-authorise. ### "Not authorized" or permission errors @@ -113,7 +99,7 @@ Your Slack workspace admin may need to approve the app. Ask your workspace admin Make sure you have at least one monitor and one status page created in your openstatus workspace before using incident commands. -## What's next? +## What's next -- **[Create a Status Page](/docs/tutorial/create-your-first-status-page)** — share your service status publicly with users -- **[Create a Monitor](/docs/tutorial/create-your-first-monitor)** — set up uptime monitoring for your endpoints +- **[Create a status page](/docs/tutorial/create-your-first-status-page)** — share your service status publicly with users. +- **[Create a monitor](/docs/tutorial/create-your-first-monitor)** — set up uptime monitoring for your endpoints. diff --git a/apps/web/src/content/pages/docs/guides/how-to-translate-status-page.mdx b/apps/web/src/content/pages/docs/guides/how-to-translate-status-page.mdx index b43b9418..c160ded3 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-translate-status-page.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-translate-status-page.mdx @@ -6,9 +6,7 @@ description: Enable multiple languages on your status page and contribute new tr openstatus status pages support multiple languages. You can configure which locales are available per page and set a default language. Visitors can switch between languages using a built-in locale switcher. -:::note -Translations are available on paid plans only. -::: + ## Supported locales @@ -24,8 +22,8 @@ Currently supported languages: ## Enable translations on your status page -1. Go to your **Dashboard** and open the status page settings. -2. Under **Locales**, select a **Default Locale** for your page. +1. Go to your **dashboard** and open the status page settings. +2. Under **Locales**, select a **default locale** for your page. 3. Check **Enable locale switcher** to allow visitors to switch languages. 4. Select which languages you want to offer. 5. Click **Submit**. diff --git a/apps/web/src/content/pages/docs/guides/how-to-use-react-widget.mdx b/apps/web/src/content/pages/docs/guides/how-to-use-react-widget.mdx index a95299ce..f8a50336 100644 --- a/apps/web/src/content/pages/docs/guides/how-to-use-react-widget.mdx +++ b/apps/web/src/content/pages/docs/guides/how-to-use-react-widget.mdx @@ -10,7 +10,7 @@ Install the [npm](https://www.npmjs.com/package/@openstatus/react) package: npm install @openstatus/react ``` -## React Server Component +## React server component ```tsx import { StatusWidget } from "@openstatus/react"; @@ -20,20 +20,17 @@ export function Page() { } ``` -It will automatically attach the slug to the href to allow the user to open a -new tab on click to `https://slug.openstatus.dev`. If you want to redirect him -to a specific page, use the `href` property, like so: +It will automatically attach the slug to the href to allow the user to open a new tab on click to `https://slug.openstatus.dev`. If you want to redirect to a specific page, use the `href` property: ```tsx ``` -> `StatusWidget` is an **async function** and will only work with RSC. Using it -> within a dead simple React App will not work. + ### Styling -#### With tailwindcss +#### With Tailwind CSS ```ts // tailwind.config.js @@ -49,7 +46,7 @@ module.exports = { }; ``` -#### Without tailwindcss +#### Without Tailwind CSS ```tsx // app/layout.tsx diff --git a/apps/web/src/content/pages/docs/guides/self-host-status-page-only.mdx b/apps/web/src/content/pages/docs/guides/self-host-status-page-only.mdx index 2cc3ebc0..9a2f9a80 100644 --- a/apps/web/src/content/pages/docs/guides/self-host-status-page-only.mdx +++ b/apps/web/src/content/pages/docs/guides/self-host-status-page-only.mdx @@ -12,7 +12,7 @@ You want a status page to communicate incidents and maintenance to your users, b openstatus provides a lightweight Docker Compose setup that runs only 4 services: a database, a one-shot migration runner, the dashboard, and the status page. This is ideal for teams who only want to self-host the status page without monitoring, or for teams that manage incidents manually using external monitoring tools. -## Lightweight vs Full +## Lightweight vs full The lightweight stack strips away all monitoring infrastructure. Here's what each version includes: @@ -36,9 +36,9 @@ If you need automated monitoring, follow the [full self-hosting guide](/docs/gui ## Step-by-step guide -### Part 1: Initial Setup and Service Launch +### Part 1: initial setup and service launch -1. **Clone the Repository** +1. **Clone the repository** Get the latest version of openstatus: ```bash @@ -46,7 +46,7 @@ If you need automated monitoring, follow the [full self-hosting guide](/docs/gui cd openstatus ``` -2. **Configure Your Environment** +2. **Configure your environment** Copy the example environment file. This is a simplified version of the full configuration, with only the variables relevant to the status page and dashboard. ```bash @@ -62,7 +62,7 @@ If you need automated monitoring, follow the [full self-hosting guide](/docs/gui Optionally, you can configure GitHub or Google OAuth providers by filling in the `AUTH_GITHUB_*` or `AUTH_GOOGLE_*` variables in the same file. -3. **Build and Start Services** +3. **Build and start services** Use Docker Compose to build and run all services in the background: ```bash @@ -78,16 +78,16 @@ If you need automated monitoring, follow the [full self-hosting guide](/docs/gui Wait until all services show as `healthy` before proceeding. The `db-migrate` service will show as exited — this is expected, as it runs once and stops. -### Part 2: Application Configuration +### Part 2: application configuration -4. **Access the Applications** +4. **Access the applications** - **Dashboard:** `http://localhost:3000` - **Status Page:** `http://localhost:3001` Log in to the dashboard using email authentication (magic link). This will create your account and workspace. -5. **Set Workspace Limits** +5. **Set workspace limits** 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`: @@ -102,13 +102,13 @@ If you need automated monitoring, follow the [full self-hosting guide](/docs/gui -d '{"statements":["SELECT id, name FROM workspace"]}' ``` -6. **Create Your Status Page** +6. **Create your status page** In the dashboard, create a new status page, add components for the services you want to display, and publish it. Your status page will be available at `http://localhost:3001`. ## Service architecture -| Service | Container | Host Port | Purpose | +| Service | Container | Host port | Purpose | |---------|-----------|-----------|---------| | libsql | openstatus-libsql | 8080 | Database (HTTP API) | | db-migrate | openstatus-db-migrate | — | One-shot database migration (exits after completion) | @@ -142,5 +142,5 @@ docker compose -f docker-compose-lightweight.yaml ps ## Next steps -- **[Self-Host openstatus (Full)](/docs/guides/self-hosting-openstatus)** — Add automated monitoring, analytics, and alerting -- **[Join our Discord](https://www.openstatus.dev/discord)** — Get help from the community +- **[Self-host openstatus (full)](/docs/guides/self-hosting-openstatus)** — add automated monitoring, analytics, and alerting. +- **[Join our Discord](https://www.openstatus.dev/discord)** — get help from the community. diff --git a/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx b/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx index 138b7e15..1690b726 100644 --- a/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx +++ b/apps/web/src/content/pages/docs/guides/self-hosting-openstatus.mdx @@ -32,9 +32,9 @@ Self-hosting openstatus currently has these constraints: This guide is divided into three parts: launching the services, setting up the database and analytics, and configuring the application through the UI. -### Part 1: Initial Setup and Service Launch +### Part 1: initial setup and service launch -1. **Clone the Repository** +1. **Clone the repository** Get the latest version of openstatus: ```bash @@ -42,7 +42,7 @@ This guide is divided into three parts: launching the services, setting up the d cd openstatus ``` -2. **Configure Your Environment** +2. **Configure your environment** Copy the example environment file. This file will hold all your configuration variables. ```bash @@ -50,7 +50,7 @@ This guide is divided into three parts: launching the services, setting up the d ``` 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. -3. **Build and Start Services** +3. **Build and start services** Use Docker Compose to build and run all openstatus services in the background. ```bash @@ -59,9 +59,9 @@ This guide is divided into three parts: launching the services, setting up the 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. -### Part 2: Database and Analytics Setup +### Part 2: database and analytics setup -4. **Run Database Migrations** +4. **Run database migrations** The database container starts with an empty database. You must run migrations to set up the required schema. ```bash @@ -96,7 +96,7 @@ This guide is divided into three parts: launching the services, setting up the d ' ``` -5. **Deploy Local Tinybird Analytics** +5. **Deploy local Tinybird analytics** Tinybird is used for analytics. Deploy the local datasources, pipes, and endpoints. ```bash @@ -107,7 +107,7 @@ This guide is divided into three parts: launching the services, setting up the d cd ../.. # Return to the project root ``` -6. **Configure Tinybird API Key** +6. **Configure Tinybird API key** You need to get your local Tinybird admin token and add it to your environment file. ```bash @@ -124,14 +124,14 @@ This guide is divided into three parts: launching the services, setting up the d docker compose restart ``` -### Part 3: Application Configuration +### Part 3: application configuration Now that the services are running, you can access the dashboard and perform the final setup steps. - **Dashboard:** `http://localhost:3002` - **Status Pages:** `http://localhost:3003` -7. **Create a Workspace and Set Limits** +7. **Create a workspace and set limits** - Navigate to the dashboard at `http://localhost:3002`. - Sign up and create a new workspace. @@ -154,7 +154,7 @@ Now that the services are running, you can access the dashboard and perform the ]}" ``` -8. **Deploy a Private Location** +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. @@ -165,7 +165,7 @@ Now that the services are running, you can access the dashboard and perform the - `OPENSTATUS_INGEST_URL`: The URL of your self-hosted server's API endpoint (e.g., `http://:3001`). - For a detailed guide on deploying a private location, see **[Deploy Private Locations on Cloudflare Containers](/docs/guides/how-to-deploy-probes-cloudflare-containers)**. -9. **Create Monitors** +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. @@ -193,29 +193,28 @@ openstatus consists of multiple services running together: ## 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 +- 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]` +**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 +**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 +**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` +**Tinybird issues** — make sure the Tinybird token is correctly set in `.env.docker`. -## Next steps +## What's next -- **[Deploy Private Locations](/docs/guides/how-to-deploy-probes-cloudflare-containers)** - Set up monitoring from multiple regions -- **[Create Monitors](/docs/tutorial/create-your-first-monitor)** - Start monitoring your services +- **[Deploy a private probe on Cloudflare Containers](/docs/guides/how-to-deploy-probes-cloudflare-containers)** — set up monitoring from multiple regions. +- **[Create your first monitor](/docs/tutorial/create-your-first-monitor)** — start monitoring your services. -## Additional resources +### Learn more -- **[Docker Compose file](https://github.com/openstatusHQ/openstatus/blob/main/docker-compose.yaml)** - Review the complete configuration -- **[Private Location Reference](/docs/reference/private-location)** - Technical specifications -- **[Join our Discord](https://www.openstatus.dev/discord)** - Get help from the community +- **[Docker Compose file](https://github.com/openstatusHQ/openstatus/blob/main/docker-compose.yaml)** — review the complete configuration. +- **[Private location reference](/docs/reference/private-location)** — technical specifications. +- **[Join our Discord](https://www.openstatus.dev/discord)** — get help from the community. diff --git a/apps/web/src/content/pages/docs/reference/cli-reference.mdx b/apps/web/src/content/pages/docs/reference/cli-reference.mdx index 61d942a4..b85d194f 100644 --- a/apps/web/src/content/pages/docs/reference/cli-reference.mdx +++ b/apps/web/src/content/pages/docs/reference/cli-reference.mdx @@ -4,8 +4,6 @@ title: CLI Reference description: Complete reference for the openstatus CLI — manage status pages, monitors, and incidents from your terminal. --- -## CLI interface - openstatus - Manage status pages, monitors, and incidents from the terminal. Usage: diff --git a/apps/web/src/content/pages/docs/reference/dns-monitor.mdx b/apps/web/src/content/pages/docs/reference/dns-monitor.mdx index 3b79e12e..b3749d28 100644 --- a/apps/web/src/content/pages/docs/reference/dns-monitor.mdx +++ b/apps/web/src/content/pages/docs/reference/dns-monitor.mdx @@ -4,15 +4,14 @@ title: DNS Monitor Reference description: Complete technical specification for DNS record monitoring --- -## Overview - -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. +A DNS monitor verifies 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 + +- 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 unauthorised DNS alterations. ## Configuration @@ -28,72 +27,20 @@ The fully qualified domain name or subdomain to be monitored. - `api.example.com` - `mail.example.org` -### Record Types +### 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. +- `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 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) +The geographical locations from which the DNS monitoring checks are performed. This allows for verification of DNS propagation and performance across different networks. See the [Location Reference](/docs/reference/location) for the full list of regions and the IPs to allowlist. ### Frequency @@ -105,7 +52,7 @@ The interval at which the DNS checks are performed. Supported frequencies: - 30 minutes - 1 hour -### Response Time Thresholds +### Response time thresholds #### Timeout @@ -129,4 +76,4 @@ The number of times the monitor will retry a failed DNS lookup before reporting ## Related resources -- **[CLI Reference](/docs/reference/cli-reference)** - Manage monitors as code using the openstatus CLI. +- **[CLI reference](/docs/reference/cli-reference)** — manage monitors as code using the openstatus CLI. diff --git a/apps/web/src/content/pages/docs/reference/http-monitor.mdx b/apps/web/src/content/pages/docs/reference/http-monitor.mdx index 15b6125d..c22af4da 100644 --- a/apps/web/src/content/pages/docs/reference/http-monitor.mdx +++ b/apps/web/src/content/pages/docs/reference/http-monitor.mdx @@ -4,11 +4,10 @@ title: HTTP Monitor Reference description: Complete technical specification for HTTP/HTTPS endpoint monitoring --- -## 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. +An HTTP monitor checks the status of HTTP and HTTPS endpoints. Use it to monitor websites, APIs, webhooks, or any other HTTP-accessible service. **Use cases:** + - Website uptime monitoring - API health checks - Webhook endpoint validation @@ -31,27 +30,29 @@ The URL of the HTTP endpoint you want to monitor. **Note:** We recommend using HTTPS for better security. -### Methods +### Method -**Type:** String (required) +**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 + +- `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` + +- Health checks: `GET`. +- API testing: `POST`, `PUT`, `DELETE`. +- Webhook testing: `POST`. ### Body @@ -87,70 +88,19 @@ 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 + +- **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 -**Type:** Array of Strings (required) +**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__ - -- 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) +The geographical regions from which the HTTP request will be triggered. This allows for monitoring global availability and performance. See the [Location Reference](/docs/reference/location) for the full list of regions and the IPs to allowlist. ### Frequency @@ -165,7 +115,7 @@ The interval at which the HTTP monitor will perform checks. Supported frequencie - `30 minutes` - `1 hour` -### Response Time Thresholds +### Response time thresholds #### Timeout @@ -189,45 +139,49 @@ The number of times the monitor will automatically retry the HTTP request upon f ### Assertions -Assertions allow you to validate specific aspects of the HTTP response. +Assertions let you validate specific aspects of the HTTP response. -#### Body Assertions +#### 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 +- `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 +- `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. + +#### Header 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. +**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:** +- `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. @@ -236,16 +190,16 @@ Validate the presence or content of specific HTTP response headers. Configures the export of monitoring metrics to an OpenTelemetry-compatible observability platform. -#### OTLP Endpoint +#### OTLP endpoint -**Type:** String (optional) +**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 +#### OTLP headers **Type:** Key-value pairs (optional) @@ -258,20 +212,21 @@ Authorization: Bearer ### Public -**Type:** Boolean +**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. +- `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](/docs/tutorial/create-your-first-monitor)** - Step-by-step tutorial on setting up a monitor. -- **[CLI Reference](/docs/reference/cli-reference)** - Guide to managing openstatus monitors programmatically using the command-line interface. +- **[Create your first monitor](/docs/tutorial/create-your-first-monitor)** — step-by-step tutorial on setting up a monitor. +- **[CLI reference](/docs/reference/cli-reference)** — manage monitors programmatically from the command line. diff --git a/apps/web/src/content/pages/docs/reference/incident.mdx b/apps/web/src/content/pages/docs/reference/incident.mdx index 845a0599..91a03b76 100644 --- a/apps/web/src/content/pages/docs/reference/incident.mdx +++ b/apps/web/src/content/pages/docs/reference/incident.mdx @@ -4,41 +4,42 @@ title: Incident Reference description: Technical specification for incident management and lifecycle --- -## Overview - 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 +- 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. +**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 -## 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](/docs/reference/status-report)). -Incidents progress through several states reflecting their current resolution status. These states are managed through status reports (see [Status Report Reference](/docs/reference/status-report)). +**Primary states:** -**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. +- `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. +- **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** — the geographical regions from which the monitor reported failures. ## Related resources -- **[Status Report Reference](/docs/reference/status-report)** - Details on how incident statuses are managed and reported. +- **[Status report reference](/docs/reference/status-report)** — details on how incident statuses are managed and reported. diff --git a/apps/web/src/content/pages/docs/reference/location.mdx b/apps/web/src/content/pages/docs/reference/location.mdx index 540d4924..8fcbf2ac 100644 --- a/apps/web/src/content/pages/docs/reference/location.mdx +++ b/apps/web/src/content/pages/docs/reference/location.mdx @@ -4,20 +4,19 @@ title: Location Reference description: Complete technical specification for Location monitoring --- -## Overview - openstatus monitors your endpoints from multiple global locations to ensure accurate uptime and latency reporting. Locations span several infrastructure providers (Fly.io, Railway, and Koyeb), so IP availability varies: Fly.io regions expose both IPv4 and IPv6 addresses, Railway regions are IPv4-only, and Koyeb does not provide static IPs. You can use these locations to: -- Configure region-specific checks -- Allowlist monitoring IPs in your firewall -- Understand where requests originate during synthetic monitoring -### Fly.io Regions & Monitoring IPs +- Configure region-specific checks. +- Allowlist monitoring IPs in your firewall. +- Understand where requests originate during synthetic monitoring. + +### Fly.io regions and monitoring IPs Below is the complete list of regions used for monitoring, along with their associated IPv4 and IPv6 addresses. -| Region Code | Location Name | IPv4 Address | IPv6 Address | +| Region code | Location name | IPv4 address | IPv6 address | |-------------|-------------------|-------------------|-------------------------------| | ams | Amsterdam | 209.71.64.1 | 2a09:8280:e601:1:0:22:b79b:0 | | arn | Stockholm | 209.71.98.189 | 2a09:8280:e602:1:0:22:b79b:0 | @@ -39,22 +38,22 @@ Below is the complete list of regions used for monitoring, along with their asso | yyz | Toronto | 209.71.99.51 | 2a09:8280:e637:1:0:22:b79b:0 | -## Railway Regions & Monitoring IPs +## Railway regions and monitoring IPs Below is the complete list of Railway regions used for monitoring, along with their associated IPv4 addresses. -| Region Code | Location Name | IPv4 Address | +| Region code | Location name | IPv4 address | |--------------------------|------------------|-------------------| | europe-west4-drams3a | Europe West | 208.77.244.15 | | asia-southeast1-eqsg3a | Asia Southeast | 208.77.246.15 | | us-east4-eqdc4a | US East | 162.220.234.15 | | us-west2 | US West | 162.220.232.99 | -## Koyeb Regions +## Koyeb regions Koyeb does not provide static IP addresses for their regions, so IPs are not available for allowlisting. For details, see Koyeb's [documentation](https://www.koyeb.com/docs/faqs/general#i-want-to-restrict-access-to-a-database-or-other-application-by-ip-address-what-ip-addresses-does-koyeb-use). -| Region Code | Location Name | +| Region code | Location name | |--------------|-------------------------| | koyeb_fra | Frankfurt, Germany | | koyeb_par | Paris, France | diff --git a/apps/web/src/content/pages/docs/reference/maintenance.mdx b/apps/web/src/content/pages/docs/reference/maintenance.mdx index 01b9783a..f8dc84bc 100644 --- a/apps/web/src/content/pages/docs/reference/maintenance.mdx +++ b/apps/web/src/content/pages/docs/reference/maintenance.mdx @@ -4,13 +4,11 @@ title: Maintenance Reference description: Technical specification for scheduled maintenance windows in openstatus. --- -## Overview - A maintenance window is a scheduled period during which you expect planned disruption to one or more services — a database upgrade, a deployment, or infrastructure work. Announcing it ahead of time lets you communicate the disruption to your users instead of letting your status page register it as an unexpected outage. A maintenance belongs to a single status page and targets one or more of that page's components — monitor-linked or static. -## Behavior +## Behaviour While a maintenance window is active (the current time is between `from` and `to`): @@ -22,7 +20,7 @@ Maintenance windows **do not** exclude downtime from uptime calculations. The up When a maintenance is created, status page subscribers can be notified that it has been scheduled (see [Notify](#notify)). Updating a maintenance never re-notifies. -## Configuration and Properties +## Configuration and properties ### Title @@ -55,13 +53,13 @@ When the maintenance window starts. When the maintenance window ends. Must be later than `from`. -### Status Page +### Status page **Type:** Integer (required) The id of the status page this maintenance belongs to. A maintenance is scoped to exactly one status page. -### Affected Components +### Affected components **Type:** Array of integers (optional) **Default:** `[]` @@ -86,6 +84,6 @@ The v1 REST API does not expose this flag; it notifies subscribers automatically ## Related resources -- **[Status Page Reference](/docs/reference/status-page)** - How maintenance windows surface on the public status page. -- **[Page Components](/docs/reference/page-components)** - The monitor and static components a maintenance window can target. -- **[Status Report Reference](/docs/reference/status-report)** - Communicate unplanned incidents, as opposed to scheduled maintenance. +- **[Status page reference](/docs/reference/status-page)** — how maintenance windows surface on the public status page. +- **[Page components](/docs/reference/page-components)** — the monitor and static components a maintenance window can target. +- **[Status report reference](/docs/reference/status-report)** — communicate unplanned incidents, as opposed to scheduled maintenance. diff --git a/apps/web/src/content/pages/docs/reference/notification.mdx b/apps/web/src/content/pages/docs/reference/notification.mdx index c55a6b43..d35d3680 100644 --- a/apps/web/src/content/pages/docs/reference/notification.mdx +++ b/apps/web/src/content/pages/docs/reference/notification.mdx @@ -4,11 +4,9 @@ title: Notification Channels Reference description: Technical specification for openstatus notification channels and alert payloads. --- -## 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. You must configure and enable specific channels to receive alerts. -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. @@ -17,8 +15,8 @@ Each notification channel requires specific configuration parameters to enable a 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. - **Example**: `https://hooks.slack.com/services/XXX/YYY/ZZZ` + +- **Incoming webhook URL** (required) — a [Slack incoming webhook URL](https://api.slack.com/incoming-webhooks) where notifications will be posted. Example: `https://hooks.slack.com/services/XXX/YYY/ZZZ`. You can [download the openstatus logo](https://www.openstatus.dev/assets/logos/openstatus.jpeg) to add a custom logo. @@ -27,39 +25,42 @@ You can [download the openstatus logo](https://www.openstatus.dev/assets/logos/o Sends alerts directly to a specified email address. **Configuration:** -- **Email Address:** (Required) The recipient's email address. + +- **Email address** (required) — the recipient's email address. ### Discord 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` + +- **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`. You can [download the openstatus logo](https://www.openstatus.dev/assets/logos/openstatus.jpeg) to add a custom logo. -### Grafana OnCall IRM +### Grafana OnCall IRM Sends notifications to a Grafana OnCall IRM. **Configuration:** -- **Webhook URL:** (Required) A [Grafana OnCall IRM webhook URL](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/configure/integrations/webhooks/incoming-webhooks/oncall-webhooks/). +- **Webhook URL** (required) — a [Grafana OnCall IRM webhook URL](https://grafana.com/docs/grafana-cloud/alerting-and-irm/irm/configure/integrations/webhooks/incoming-webhooks/oncall-webhooks/). ### Google Chat 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. + +- **Webhook URL** (required) — a [Google Chat webhook URL](https://developers.google.com/workspace/chat/quickstart/webhooks) for the target space. ### SMS 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`). + +- **Phone number** (required) — the recipient's phone number in international format (e.g., `+14155552671`). **Note:** SMS delivery can vary by country due to provider routing. Contact support if delivery issues are encountered. WhatsApp notifications may be an alternative. @@ -68,26 +69,29 @@ Sends alerts as SMS messages to a mobile phone number. 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`). + +- **Phone number** (required) — the recipient's phone number in international format (e.g., `+14155552671`). ### Telegram Delivers alerts to a specified Telegram chat. **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. -**Bot ID:** The official openstatus Telegram bot ID is `@openstatushq_bot`. +- **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. + +**Bot ID:** the official openstatus Telegram bot ID is `@openstatushq_bot`. ### Webhook 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 Payload +- **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 payload Every webhook notification — `error`, `degraded`, and `recovered` — uses the same flat JSON payload. `statusCode`, `latency`, and `errorMessage` are optional on **every** status; the sender includes whichever apply to the check. @@ -106,7 +110,7 @@ Every webhook notification — `error`, `degraded`, and `recovered` — uses the } ``` -**Payload Fields:** +**Payload fields:** | Field | Type | Description | | :------------- | :------- | :------------------------------------------------------------------- | @@ -123,7 +127,7 @@ Every webhook notification — `error`, `degraded`, and `recovered` — uses the Webhook requests carry **no payload signature or HMAC**. The only verification mechanism is the custom headers you configure (e.g. a shared-secret header such as `Authorization` or `x-webhook-secret`) — validate one of those on your endpoint. -#### Zod Schema +#### Zod schema The validation schema for webhook payloads: @@ -149,24 +153,27 @@ export const PayloadSchema = z.object({ Integrates with OpsGenie for incident management. **Configuration:** -- **API Key:** (Required) An API key obtained from your OpsGenie account. + +- **API key** (required) — an API key obtained from your OpsGenie account. ### PagerDuty 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. + +- **Integration steps** (required) — follow the specific integration steps provided within the PagerDuty workflow to set up this channel. ### Ntfy 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. + +- **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 -- **[Incident Reference](/docs/reference/incident)** - Information about incident creation and management. +- **[Incident reference](/docs/reference/incident)** — information about incident creation and management. diff --git a/apps/web/src/content/pages/docs/reference/overview.mdx b/apps/web/src/content/pages/docs/reference/overview.mdx index 67884580..ef8bec5a 100644 --- a/apps/web/src/content/pages/docs/reference/overview.mdx +++ b/apps/web/src/content/pages/docs/reference/overview.mdx @@ -10,39 +10,39 @@ This section is the source of truth for openstatus configuration. Use it to look How each monitor type runs checks and what you can configure on it. -- **[HTTP Monitor](/docs/reference/http-monitor)** — URL, method, headers, body, assertions, regions. -- **[TCP Monitor](/docs/reference/tcp-monitor)** — host:port checks for non-HTTP services. -- **[DNS Monitor](/docs/reference/dns-monitor)** — record-type assertions for A, AAAA, CNAME, MX, NS, TXT. +- **[HTTP monitor](/docs/reference/http-monitor)** — URL, method, headers, body, assertions, regions. +- **[TCP monitor](/docs/reference/tcp-monitor)** — host:port checks for non-HTTP services. +- **[DNS monitor](/docs/reference/dns-monitor)** — record-type assertions for A, AAAA, CNAME, MX, NS, TXT. ## Status pages Public surfaces for communicating service health. -- **[Status Page](/docs/reference/status-page)** — page settings, custom domains, IP restrictions, themes, locales. -- **[Page Components](/docs/reference/page-components)** — monitor-linked and static components, component groups, ordering. -- **[Status Report](/docs/reference/status-report)** — incident updates and the state machine they drive. +- **[Status page](/docs/reference/status-page)** — page settings, custom domains, IP restrictions, themes, locales. +- **[Page components](/docs/reference/page-components)** — monitor-linked and static components, component groups, ordering. +- **[Status report](/docs/reference/status-report)** — incident updates and the state machine they drive. - **[Maintenance](/docs/reference/maintenance)** — scheduled maintenance windows. - **[Subscriber](/docs/reference/subscriber)** — email subscribers to a status page. ## Alerting -- **[Notification Channels](/docs/reference/notification)** — Slack, Discord, Email, SMS, WhatsApp, Telegram, PagerDuty, OpsGenie, Google Chat, Grafana OnCall, Ntfy, and generic webhooks. +- **[Notification channels](/docs/reference/notification)** — Slack, Discord, Email, SMS, WhatsApp, Telegram, PagerDuty, OpsGenie, Google Chat, Grafana OnCall, Ntfy, and generic webhooks. - **[Incident](/docs/reference/incident)** — auto-generated incident objects, trigger thresholds, and lifecycle states. ## Probing infrastructure - **[Location](/docs/reference/location)** — every public region, its provider, and the IPv4/IPv6 addresses to allowlist. -- **[Private Location](/docs/reference/private-location)** — fields for a customer-deployed probe and the API surface that manages it. +- **[Private location](/docs/reference/private-location)** — fields for a customer-deployed probe and the API surface that manages it. ## Tooling - **[CLI](/docs/reference/cli-reference)** — every command, subcommand, and flag in the `openstatus` CLI. -- **[Terraform Provider](/docs/reference/terraform)** — resource and data source schemas for `openstatusHQ/openstatus`. -- **[MCP Server](/docs/reference/mcp-server)** — tools and transport for the openstatus Model Context Protocol server. +- **[Terraform provider](/docs/reference/terraform)** — resource and data source schemas for `openstatusHQ/openstatus`. +- **[MCP server](/docs/reference/mcp-server)** — tools and transport for the openstatus Model Context Protocol server. ## HTTP API The HTTP API has its own dedicated documentation, generated from the OpenAPI schema: -- **[API Reference (current)](https://api.openstatus.dev/openapi)** — the OpenAPI document, machine-readable, always up to date with the deployed server. -- **[API Reference V1 (deprecated)](https://api.openstatus.dev/v1)** — the legacy V1 surface; kept available for existing integrations. +- **[API reference (current)](https://api.openstatus.dev/openapi)** — the OpenAPI document, machine-readable, always up to date with the deployed server. +- **[API reference v1 (deprecated)](https://api.openstatus.dev/v1)** — the legacy v1 surface; kept available for existing integrations. diff --git a/apps/web/src/content/pages/docs/reference/page-components.mdx b/apps/web/src/content/pages/docs/reference/page-components.mdx index 43f60f00..abe31c0a 100644 --- a/apps/web/src/content/pages/docs/reference/page-components.mdx +++ b/apps/web/src/content/pages/docs/reference/page-components.mdx @@ -5,22 +5,21 @@ description: Complete specification for openstatus page components on status pag --- -## Overview - -Page components are the individual elements displayed on your status page that show the operational status of your services. They provide a flexible way to organize and present both monitored services and static content on your status page. +Page components are the individual elements displayed on your status page that show the operational status of your services. They provide a flexible way to organise and present both monitored services and static content on your status page. **Key features:** + - Support for both monitor-linked and static components. -- Organize components into logical groups. +- Organise components into logical groups. - Custom ordering and arrangement. - Individual status tracking with incidents, reports, and maintenances. - Granular control over what appears on your status page. -## Component Types +## Component types Page components come in two distinct types, each serving different purposes on your status page. -### Monitor Components +### Monitor components **Type:** `monitor` @@ -39,7 +38,7 @@ Monitor components are linked to an active monitor in your workspace. They autom - Tracking critical service dependencies. - Monitoring infrastructure components. -#### Configuring Monitor Components +#### Configuring monitor components When you create a monitor component, you link it to an existing monitor in your workspace. This connection provides several benefits: @@ -72,17 +71,19 @@ You can customize the component name to be different from the monitor name. For **Status hierarchy:** -1. **Error** - Active incidents from the linked monitor. -2. **Degraded** - Unresolved status reports affecting this component. -3. **Info** - Ongoing scheduled maintenance. -4. **Success** - Healthy and operational. + +1. **Error** — active incidents from the linked monitor. +2. **Degraded** — unresolved status reports affecting this component. +3. **Info** — ongoing scheduled maintenance. +4. **Success** — healthy and operational. **What affects monitor components:** -- ✅ Automatic incidents (from monitor failures) -- ✅ Manual status reports -- ✅ Scheduled maintenances -### Static Components +- Automatic incidents (from monitor failures). +- Manual status reports. +- Scheduled maintenances. + +### Static components **Type:** `static` @@ -106,7 +107,7 @@ Static components are independent elements not linked to any monitor. They allow Static components **only** respond to manual status reports and scheduled maintenances. They never automatically detect issues or create incidents. If you need automatic failure detection, use a monitor component instead. -#### Managing Static Components +#### Managing static components Static components give you full manual control over what your visitors see: @@ -132,16 +133,18 @@ Static components do not perform any health checks or generate incidents. You ar - Communicating maintenance windows in advance. **Status hierarchy:** -1. **Degraded** - Unresolved status reports affecting this component. -2. **Info** - Ongoing scheduled maintenance. -3. **Success** - No active reports or maintenances. + +1. **Degraded** — unresolved status reports affecting this component. +2. **Info** — ongoing scheduled maintenance. +3. **Success** — no active reports or maintenances. **What affects static components:** -- ✅ Manual status reports -- ✅ Scheduled maintenances -- ❌ Automatic incidents (not supported) -## Component Groups +- Manual status reports. +- Scheduled maintenances. +- Automatic incidents are **not** supported. + +## Component groups Component groups allow you to organize related page components into logical sections on your status page. Groups improve readability and help visitors understand your service architecture. @@ -153,7 +156,7 @@ Component groups allow you to organize related page components into logical sect **Examples of grouping strategies:** -| Group Name | Components | +| Group name | Components | |------------|------------| | **API Services** | Authentication API, Data API, WebSocket API | | **Infrastructure** | Database, Cache, Message Queue | @@ -161,83 +164,90 @@ Component groups allow you to organize related page components into logical sect | **Regional Services** | US Region, EU Region, APAC Region | **Group configuration:** -- **Name:** The group heading displayed on your status page. -- **Order:** Position of the group relative to other groups and ungrouped components. -- **Components:** The page components contained within this group. -## Events and Status + +- **Name** — the group heading displayed on your status page. +- **Order** — position of the group relative to other groups and ungrouped components. +- **Components** — the page components contained within this group. + +## Events and status Page components can be affected by up to three types of events that influence their displayed status. The type of component determines which events apply: -| Event Type | Monitor Components | Static Components | +| Event type | Monitor components | Static components | |------------|-------------------|-------------------| -| **Incidents** | ✅ Automatic | ❌ Not supported | -| **Status Reports** | ✅ Manual | ✅ Manual | -| **Maintenances** | ✅ Manual | ✅ Manual | +| **Incidents** | Automatic | Not supported | +| **Status reports** | Manual | Manual | +| **Maintenances** | Manual | Manual | ### Incidents -**Applies to:** Monitor components only +**Applies to:** monitor components only. Incidents are automatically generated when a monitor detects a failure. They represent unplanned outages or degraded performance discovered through active monitoring. **How incidents are created:** + - Monitor check fails (connection timeout, HTTP error, DNS failure). - Monitor assertion fails (wrong status code, unexpected response body). - Monitor reaches degraded threshold (response time too slow). -**Status impact:** Components with active incidents show an **error** status. This takes the highest priority in the status hierarchy. +**Status impact:** components with active incidents show an **error** status. This takes the highest priority in the status hierarchy. -**Resolution:** Incidents are automatically resolved when the monitor recovers and checks succeed again. +**Resolution:** incidents are automatically resolved when the monitor recovers and checks succeed again. -### Status Reports +### Status reports -**Applies to:** Both monitor and static components +**Applies to:** both monitor and static components. Status reports are manually created updates about component health or issues. They provide a way to communicate problems that may not trigger automatic monitoring or to manually report issues with static components. -**Status impact:** Components with unresolved status reports show a **degraded** status (unless overridden by an incident for monitor components). +**Status impact:** components with unresolved status reports show a **degraded** status (unless overridden by an incident for monitor components). **Use cases for monitor components:** + - Reporting known issues that don't cause complete outages. - Communicating performance degradation not captured by monitoring. - Providing context for intermittent issues. **Use cases for static components:** + - Reporting third-party service issues (e.g., "Stripe processing delays"). - Communicating external service degradation. - Announcing partial outages of non-monitored systems. -**Attaching to components:** When creating a status report, you can select which components are affected. Multiple components can be attached to a single report. +**Attaching to components:** when creating a status report, you can select which components are affected. Multiple components can be attached to a single report. ### Maintenances -**Applies to:** Both monitor and static components +**Applies to:** both monitor and static components. Maintenances are scheduled maintenance windows that you create in advance. They inform visitors about planned downtime or service interruptions for both monitored and static components. -**Status impact:** Components with ongoing maintenances show an **info** status (unless overridden by incidents or reports). +**Status impact:** components with ongoing maintenances show an **info** status (unless overridden by incidents or reports). **Use cases for monitor components:** + - Scheduled system upgrades that will cause downtime. - Infrastructure changes that affect monitored services. - Planned deployments requiring service restarts. **Use cases for static components:** + - Third-party maintenance windows (e.g., "Payment provider scheduled maintenance"). - External service upgrade notifications. - Planned downtime for non-monitored dependencies. -**Scheduling:** Maintenances have a defined start and end time. The info status automatically appears during the window and disappears when the maintenance ends. +**Scheduling:** maintenances have a defined start and end time. The info status automatically appears during the window and disappears when the maintenance ends. -**Attaching to components:** When creating a maintenance, you select which components will be affected. This allows you to communicate maintenance impact across multiple services. +**Attaching to components:** when creating a maintenance, you select which components will be affected. This lets you communicate maintenance impact across multiple services. -## Managing Components +## Managing components -### Adding Components +### Adding components You can add components to your status page in two ways: @@ -249,56 +259,58 @@ When adding a monitor component, you can only select from monitors that: - Have not been deleted. - Are not already linked to another component on this status page. -### Reordering Components +### Reordering components Components and groups can be reordered using drag-and-drop functionality in the dashboard. The order determines how they appear on your status page from top to bottom. **Ordering tips:** + - Place your most critical services at the top. - Group related services together. - Consider visitor priorities when ordering. -### Editing Components +### Editing components You can modify the following properties of existing components: + - Component name and description. - Group assignment (move between groups or make ungrouped). - Display order. -**Note:** You cannot change a component's type (monitor to static or vice versa) after creation. To change types, delete the component and create a new one. +**Note:** you cannot change a component's type (monitor to static or vice versa) after creation. To change types, delete the component and create a new one. -### Deleting Components +### Deleting components When you delete a component, any associations with status reports and maintenances are automatically removed. The linked monitor (if applicable) is not deleted and remains available in your workspace. -**Warning:** Deletion is permanent and cannot be undone. Ensure you want to remove the component before confirming deletion. +**Warning:** deletion is permanent and cannot be undone. Ensure you want to remove the component before confirming deletion. -## Deprecation Notice +## Deprecation notice -The legacy monitor-only system for status pages is deprecated in favor of the more flexible page component system. +The legacy monitor-only system for status pages is deprecated in favour of the more flexible page component system. **Deprecated approach:** + - Status pages directly referenced monitors. - No support for static content. -- Limited organizational flexibility. +- Limited organisational flexibility. **Current approach (page components):** + - Status pages contain page components. - Components can be monitors or static content. - Full support for grouping and custom ordering. - Better separation between monitoring and status page presentation. -### API Compatibility +### API compatibility -**v1 API (backward compatibility):** -The v1 API continues to display `monitorIds` and `monitors` fields in status page responses to avoid breaking changes for existing integrations. However, these fields now only include page components that are explicitly of type `monitor`. Static components are not included in these legacy fields. +**v1 API (backward compatibility):** the v1 API continues to display `monitorIds` and `monitors` fields in status page responses to avoid breaking changes for existing integrations. However, these fields now only include page components that are explicitly of type `monitor`. Static components are not included in these legacy fields. -**Future API versions:** -Newer API versions will primarily use the `pageComponents` structure. The legacy `monitors` and `monitorIds` fields will be removed in future API versions. We recommend migrating your integrations to use `pageComponents` for full feature support. +**Future API versions:** newer API versions will primarily use the `pageComponents` structure. The legacy `monitors` and `monitorIds` fields will be removed in future API versions. We recommend migrating your integrations to use `pageComponents` for full feature support. ## Related resources -- **[Status Page Reference](/docs/reference/status-page)** - Complete status page configuration reference. -- **[Status Report Reference](/docs/reference/status-report)** - Details on creating and managing status reports. -- **[Create Status Page](/docs/tutorial/create-your-first-status-page)** - Step-by-step tutorial on creating a status page. -- **[HTTP Monitor Reference](/docs/reference/http-monitor)** - Technical specification for HTTP monitors that can be linked to components. +- **[Status page reference](/docs/reference/status-page)** — complete status page configuration reference. +- **[Status report reference](/docs/reference/status-report)** — details on creating and managing status reports. +- **[Create a status page](/docs/tutorial/create-your-first-status-page)** — step-by-step tutorial on creating a status page. +- **[HTTP monitor reference](/docs/reference/http-monitor)** — technical specification for HTTP monitors that can be linked to components. diff --git a/apps/web/src/content/pages/docs/reference/private-location.mdx b/apps/web/src/content/pages/docs/reference/private-location.mdx index a7be3cde..66a27919 100644 --- a/apps/web/src/content/pages/docs/reference/private-location.mdx +++ b/apps/web/src/content/pages/docs/reference/private-location.mdx @@ -4,51 +4,51 @@ title: Private Location Reference description: Technical specification for configuring and utilizing private monitoring locations. --- -## Overview - -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). +A private location in openstatus lets you deploy monitoring probes within your own infrastructure or private networks. This 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 +- **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. +When a private location is configured, openstatus provides a container image 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. +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 visualisation. ## 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. +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. ## Current API surface Private locations can currently be created, listed, updated, and deleted from the authenticated dashboard API. The supported private location fields are: -- `name`: the display name shown in the dashboard. -- `token`: the probe authentication token. -- `monitors`: the monitor IDs attached to the private location. -- `lastSeenAt`: the last time the private location probe connected. +- `name` — the display name shown in the dashboard. +- `token` — the probe authentication token. +- `monitors` — the monitor IDs attached to the private location. +- `lastSeenAt` — the last time the private location probe connected. Additional display metadata such as country, city, or hosting provider is not currently part of the private location model. If you need that information today, include it in the location name, for example `Frankfurt - Hetzner`. -**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. +**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](/docs/guides/how-to-deploy-probes-cloudflare-containers)** - A guide for deploying private probes using Cloudflare Workers/Containers. (Example deployment guide) -- **[CLI Reference](/docs/reference/cli-reference)** - Manage monitors as code, including those utilizing private locations. +- **[How to deploy probes on Cloudflare Containers](/docs/guides/how-to-deploy-probes-cloudflare-containers)** — a guide for deploying private probes using Cloudflare Workers and Containers. +- **[CLI reference](/docs/reference/cli-reference)** — manage monitors as code, including those using private locations. diff --git a/apps/web/src/content/pages/docs/reference/status-page.mdx b/apps/web/src/content/pages/docs/reference/status-page.mdx index 028fb1de..bddb8c1b 100644 --- a/apps/web/src/content/pages/docs/reference/status-page.mdx +++ b/apps/web/src/content/pages/docs/reference/status-page.mdx @@ -4,20 +4,19 @@ title: Status Page Reference description: Complete technical specification for openstatus status page configuration. --- -## 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. +A status page is a dedicated web interface 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. -- Multi-language support with a locale switcher. + +- Real-time service status updates. +- Incident communication and history. +- Customisable branding and domain. +- Multiple access control options. +- Multi-language support with a locale switcher. ## Configuration -openstatus provides several configuration options to customize your status page's appearance, accessibility, and functionality. +openstatus provides several configuration options to customise your status page's appearance, accessibility, and functionality. ### Slug @@ -26,39 +25,39 @@ openstatus provides several configuration options to customize your status page' 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 +### Custom domain **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`. +Lets you host your status page on a custom domain. Once configured, your status page will be accessible at `https://your-custom-domain.com`. -**DNS Configuration:** +**DNS configuration:** | Domain type | Record | Name | Value | TTL | |---|---|---|---|---| | Subdomain (e.g., `status.example.com`) | CNAME | `status` | `cname.vercel-dns.com` | 86400 | | Apex domain (e.g., `example.com`) | A | `@` | `76.76.21.21` | 86400 | -**Domain verification (conditional):** If your domain is already registered on another Vercel project, a TXT record will be required to prove ownership. The dashboard will display the exact TXT record name and value when this step is needed. +**Domain verification (conditional):** if your domain is already registered on another Vercel project, a TXT record will be required to prove ownership. The dashboard will display the exact TXT record name and value when this step is needed. After saving your custom domain in the dashboard, the exact DNS records will be displayed with any additional verification steps needed. -### Password (Basic Auth) +### Password (basic auth) **Type:** String (optional) 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. -**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. +**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) **Type:** Boolean (add-on feature) 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. -### IP Restriction (Network Auth) +### IP restriction (network auth) **Type:** String (add-on feature) @@ -67,12 +66,12 @@ Restricts access to your status page based on client IPv4 addresses. You provide Visitors from outside the allowed ranges are redirected to a static "Access Restricted" page — there is no login flow since IP-based access cannot be changed by the user. **Configuration:** + - Set `access_type` to `ip-restriction` in the dashboard or API. -- Provide `allowed_ip_ranges` as a comma-separated list of IPv4 CIDR ranges (we automatically - append /32 to single IPs). -- IPv6 is not supported +- Provide `allowed_ip_ranges` as a comma-separated list of IPv4 CIDR ranges (we automatically append `/32` to single IPs). +- IPv6 is not supported. -**Note:** This feature is available as a paid add-on for Starter and Pro plans. +**Note:** this feature is available as a paid add-on for Starter and Pro plans. ### Favicon @@ -80,7 +79,7 @@ Visitors from outside the allowed ranges are redirected to a static "Access Rest Allows you to upload a custom favicon that will appear in browser tabs and bookmarks for your status page. SVG files are sanitized server-side and must be under 100KB. -### JSON Feed +### JSON feed **Type:** Read-only endpoint **Format:** JSON @@ -89,17 +88,17 @@ Provides a machine-readable JSON representation of your status page data. This f **Example:** `https://status.openstatus.dev/feed/json` -**Deprecation Notice:** +**Deprecation notice:** The following fields are deprecated and will be removed in a future version: -- **`monitors`** (top-level): Use `pageComponents` instead, which provides a more flexible component-based structure that supports both monitors and external services. -- **`maintenances[].monitors`**: Use `maintenances[].pageComponents` instead, which references page component IDs rather than monitor IDs. -- **`statusReports[].monitors`**: Use `statusReports[].pageComponents` instead, which references page component IDs rather than monitor IDs. +- **`monitors`** (top-level) — use `pageComponents` instead, which provides a more flexible component-based structure that supports both monitors and external services. +- **`maintenances[].monitors`** — use `maintenances[].pageComponents` instead, which references page component IDs rather than monitor IDs. +- **`statusReports[].monitors`** — use `statusReports[].pageComponents` instead, which references page component IDs rather than monitor IDs. These deprecated fields are currently maintained for backward compatibility but may be removed in future versions. -### SSH Command +### SSH command **Type:** Command-line utility @@ -122,14 +121,15 @@ Enables multi-language support for your status page. You can set a default local **Supported locales:** `en` (English), `fr` (Français), `de` (Deutsch) **Configuration:** -- **Default Locale** — the fallback language for your status page (defaults to `en`). -- **Locale Switcher** — when enabled, visitors see a language dropdown. You select which locales to offer. -**Routing:** The default locale is omitted from the URL (`as-needed` prefix). Non-default locales appear in the path (e.g., `/fr/events`). +- **Default locale** — the fallback language for your status page (defaults to `en`). +- **Locale switcher** — when enabled, visitors see a language dropdown. You select which locales to offer. + +**Routing:** the default locale is omitted from the URL (`as-needed` prefix). Non-default locales appear in the path (e.g., `/fr/events`). See [How to translate your status page](/docs/guides/how-to-translate-status-page) for setup instructions and contributing new translations. -### White Label +### White label **Type:** Boolean (add-on feature) @@ -137,7 +137,7 @@ Removes the "powered by openstatus.dev" footer from your status page, providing ## Related resources -- **[Create Status Page](/docs/tutorial/create-your-first-status-page)** - Step-by-step tutorial on creating a status page. -- **[How to Configure Status Page](/docs/guides/how-to-configure-status-page)** - Guide on advanced status page configuration. -- **[Status Report Reference](/docs/reference/status-report)** - Details on how incident statuses are managed and reported. -- **[How to Translate Your Status Page](/docs/guides/how-to-translate-status-page)** - Enable multiple languages and contribute translations. +- **[Create a status page](/docs/tutorial/create-your-first-status-page)** — step-by-step tutorial on creating a status page. +- **[How to configure a status page](/docs/guides/how-to-configure-status-page)** — advanced status page configuration. +- **[Status report reference](/docs/reference/status-report)** — how incident statuses are managed and reported. +- **[How to translate your status page](/docs/guides/how-to-translate-status-page)** — enable multiple languages and contribute translations. diff --git a/apps/web/src/content/pages/docs/reference/status-report.mdx b/apps/web/src/content/pages/docs/reference/status-report.mdx index fdc665f9..fb1dd444 100644 --- a/apps/web/src/content/pages/docs/reference/status-report.mdx +++ b/apps/web/src/content/pages/docs/reference/status-report.mdx @@ -4,33 +4,32 @@ title: Status Report Reference description: Technical specification for incident status updates within openstatus. --- -## 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. **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 +- Document the lifecycle and progress of an incident. +- Communicate current incident status and actions taken. +- 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 +## Configuration and properties A status report consists of several key properties that define its content and context. ### Status -**Type:** Enumerated String (required) +**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`: 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. +- `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 @@ -45,13 +44,14 @@ The timestamp indicating when the status report was created or when the reported 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."` +**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](/docs/reference/incident)** - Detailed information on incident creation and lifecycle. -- **[Status Page Reference](/docs/reference/status-page)** - Information on how status reports are displayed on public status pages. +- **[Incident reference](/docs/reference/incident)** — detailed information on incident creation and lifecycle. +- **[Status page reference](/docs/reference/status-page)** — how status reports are displayed on public status pages. diff --git a/apps/web/src/content/pages/docs/reference/subscriber.mdx b/apps/web/src/content/pages/docs/reference/subscriber.mdx index def6a3ac..cfe556e8 100644 --- a/apps/web/src/content/pages/docs/reference/subscriber.mdx +++ b/apps/web/src/content/pages/docs/reference/subscriber.mdx @@ -4,42 +4,41 @@ title: Subscriber Reference description: Technical specification for managing status page subscribers and their notifications. --- -## Overview - 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 +- 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. +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 the 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) to receive updates through, if multiple options are available. -## Notification Types Received +## 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). -- **Scheduled Maintenance:** When a maintenance window is created on the page, subscribers can be notified that it has been scheduled (see the [Maintenance Reference](/docs/reference/maintenance)). +- **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). +- **Scheduled maintenance** — when a maintenance window is created on the page, subscribers can be notified that it has been scheduled (see the [maintenance reference](/docs/reference/maintenance)). -## Subscriber Management +## 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). +- **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](/docs/reference/status-page)** - Detailed information on managing and configuring status pages. -- **[Notification Channels Reference](/docs/reference/notification)** - Technical specifications for the various notification delivery methods. -- **[Incident Reference](/docs/reference/incident)** - Information about incident creation and management. +- **[Status page reference](/docs/reference/status-page)** — detailed information on managing and configuring status pages. +- **[Notification channels reference](/docs/reference/notification)** — technical specifications for the various notification delivery methods. +- **[Incident reference](/docs/reference/incident)** — information about incident creation and management. diff --git a/apps/web/src/content/pages/docs/reference/tcp-monitor.mdx b/apps/web/src/content/pages/docs/reference/tcp-monitor.mdx index 9156be31..e23a41cc 100644 --- a/apps/web/src/content/pages/docs/reference/tcp-monitor.mdx +++ b/apps/web/src/content/pages/docs/reference/tcp-monitor.mdx @@ -4,15 +4,14 @@ title: TCP Monitor Reference description: Complete technical specification for TCP service monitoring. --- -## Overview - -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. +A TCP monitor 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. + +- 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 @@ -30,62 +29,10 @@ The endpoint of the TCP service you want to monitor. This includes the hostname ### Regions -**Type:** Array of Strings (required) +**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__ - -- 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) +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. See the [Location Reference](/docs/reference/location) for the full list of regions and the IPs to allowlist. ### Frequency @@ -100,7 +47,7 @@ The interval at which the TCP monitor will attempt to connect to the target URI. - `30 minutes` - `1 hour` -### Response Time Thresholds +### Response time thresholds #### Timeout @@ -126,14 +73,14 @@ The number of times the monitor will automatically retry a failed TCP connection Configures the export of monitoring metrics to an OpenTelemetry-compatible observability platform. -#### OTLP Endpoint +#### 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 +#### OTLP headers **Type:** Key-value pairs (optional) @@ -146,5 +93,5 @@ Authorization: Bearer ## Related resources -- **[Create Your First Monitor](/docs/tutorial/create-your-first-monitor)** - Step-by-step tutorial on setting up a monitor. -- **[CLI Reference](/docs/reference/cli-reference)** - Guide to managing openstatus monitors programmatically using the command-line interface. +- **[Create your first monitor](/docs/tutorial/create-your-first-monitor)** — step-by-step tutorial on setting up a monitor. +- **[CLI reference](/docs/reference/cli-reference)** — manage monitors programmatically from the command line. diff --git a/apps/web/src/content/pages/docs/reference/terraform.mdx b/apps/web/src/content/pages/docs/reference/terraform.mdx index 2ee34904..2a793c0d 100644 --- a/apps/web/src/content/pages/docs/reference/terraform.mdx +++ b/apps/web/src/content/pages/docs/reference/terraform.mdx @@ -4,15 +4,14 @@ title: Terraform Provider Reference description: Technical specification for the openstatus Terraform Provider. --- -## Overview - -The openstatus Terraform provider enables you to manage your monitoring infrastructure programmatically using HashiCorp Terraform. Define monitors, notification channels, and status pages as code — with full support for version control, automated deployments, and IaC workflows. +The openstatus Terraform provider lets you manage your monitoring infrastructure programmatically using HashiCorp Terraform. Define monitors, notification channels, and status pages as code — with full support for version control, automated deployments, and IaC workflows. **Key capabilities:** -- Manage HTTP, TCP, and DNS monitors with assertions -- Configure notification channels (Slack, PagerDuty, email, webhooks, and more) -- Create and manage status pages with component groups -- Import existing resources into Terraform state + +- Manage HTTP, TCP, and DNS monitors with assertions. +- Configure notification channels (Slack, PagerDuty, email, webhooks, and more). +- Create and manage status pages with component groups. +- Import existing resources into Terraform state. ## Installation @@ -31,7 +30,7 @@ terraform { For the latest version, refer to the [Terraform Registry](https://registry.terraform.io/providers/openstatusHQ/openstatus/latest). -## Provider Configuration +## Provider configuration ```terraform provider "openstatus" { diff --git a/apps/web/src/content/pages/docs/tutorial/create-your-first-monitor.mdx b/apps/web/src/content/pages/docs/tutorial/create-your-first-monitor.mdx index b79a5108..82977917 100644 --- a/apps/web/src/content/pages/docs/tutorial/create-your-first-monitor.mdx +++ b/apps/web/src/content/pages/docs/tutorial/create-your-first-monitor.mdx @@ -6,34 +6,21 @@ description: "Set up your first uptime monitor with openstatus — track respons -## What you'll learn - | | | |---|---| | **Time** | ~5 minutes | | **Level** | Beginner | | **Prerequisites** | openstatus account, a public URL to monitor | -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. - -### 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 +In this tutorial, you'll 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. +By the end you'll have a working uptime monitor checking your endpoint every minute, real-time metrics showing response time and status codes, and a sense of how to customise HTTP requests for different scenarios. -## Get Started in 1 Minute +## Get started in 1 minute Let's get your first uptime check up and running. -### 1. Create the Monitor +### 1. Create the monitor -## Important Considerations +## Important considerations -### Monitoring Third-Party Endpoints +### Monitoring third-party endpoints