Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
chore: new docs (#2236)
Thibault Le Ouayf5ce5a13bf3c
diff --git a/apps/web/src/content/docs.config.ts b/apps/web/src/content/docs.config.tsindex 2316988b1..f3af1277f 100644--- a/apps/web/src/content/docs.config.ts+++ b/apps/web/src/content/docs.config.ts@@ -38,6 +38,14 @@ export const docsNav: DocsNavSection[] = [slug: "concept/uptime-monitoring",label: "Understanding Uptime Monitoring",},+ {+ slug: "concept/probes-and-locations",+ label: "Probes, Locations, and Regions",+ },+ {+ slug: "concept/private-locations",+ label: "Understanding Private Locations",+ },{slug: "concept/best-practices-status-page",label: "Building Trust with Status Pages",@@ -65,10 +73,18 @@ export const docsNav: DocsNavSection[] = [slug: "tutorial/how-to-create-monitor",label: "Create an Uptime Monitor in 5 Minutes",},+ {+ slug: "tutorial/your-first-notification",+ label: "Wire Up Your First Notification",+ },{slug: "tutorial/how-to-create-status-page",label: "Create a Status Page",},+ {+ slug: "tutorial/your-first-status-report",+ label: "Publish Your First Status Report",+ },{slug: "tutorial/how-to-configure-status-page",label: "Configure Your Status Page",@@ -192,6 +208,7 @@ export const docsNav: DocsNavSection[] = [label: "Reference",collapsed: true,items: [+ { slug: "reference/overview", label: "Overview" },{link: "https://api.openstatus.dev/v1",label: "API Reference V1 - Deprecated",diff --git a/apps/web/src/content/pages/docs/concept/private-locations.mdx b/apps/web/src/content/pages/docs/concept/private-locations.mdxnew file mode 100644index 000000000..ef37822ef--- /dev/null+++ b/apps/web/src/content/pages/docs/concept/private-locations.mdx@@ -0,0 +1,69 @@+---+category: Concepts+title: Understanding Private Locations+description: "What a private location is, when to use one, how it talks to openstatus, and how it differs from a public probe."+---++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).++## When a private location is the right tool++Public probes can only reach what's reachable from the public internet. Anything behind a firewall, on a VPC, or on an internal-only DNS name is invisible to them. A private location lives inside that network boundary and can reach those endpoints directly.++Concretely, reach for a private location when you need to monitor:++- Internal APIs and services behind a corporate firewall or VPC.+- Databases, message brokers, or other backing services that don't expose a public port.+- Services in a region openstatus doesn't offer a public probe in.+- An endpoint where the *path* the request takes matters — e.g. a check from your production VPC validates the same network policy your app traffic depends on.++If your endpoint is already public and you only want geographic coverage, the [public locations](/docs/reference/location) are simpler and cheaper to operate.++## How the connection works++A private location is not an inbound port openstatus calls into. The probe initiates everything:++1. You deploy the openstatus probe container — typically `ghcr.io/openstatushq/probe:latest` — somewhere inside the network that needs to be monitored.+2. The probe opens an outbound, authenticated connection to the openstatus platform using the token issued when you created the location.+3. openstatus dispatches the checks assigned to that location down the connection. The probe runs them against your internal endpoints and streams the results back.++The consequence is that you only need **outbound** network access from the probe to `api.openstatus.dev` on port 443. No inbound firewall rules, no exposed ports, no reverse tunnel — the same shape as any other agent that calls home.++## How it differs from a public location++| | Public location | Private location |+| --- | --- | --- |+| Operator | openstatus | You |+| Network reach | Public internet only | Whatever the probe host can reach |+| IPs to allowlist | [Documented per region](/docs/reference/location) | Yours |+| Cost model | Included with monitor checks | You pay for the host/container |+| Auto-incident & alerts | Yes | Not yet (see limitations below) |+| Use on public status pages | Yes | Not yet (see limitations below) |++A monitor can be assigned to public locations, private locations, or both. Public-and-private hybrids are useful when you want a public probe for SLA reporting and a private probe for in-network diagnostics on the same endpoint.++## Trade-offs to know about++Running a private location moves operational responsibility to you. Plan for:++- **Probe availability.** If your probe host is down, openstatus can't run checks from it. Treat the probe as part of your own infrastructure — restart policy, host monitoring, log retention.+- **Token handling.** The probe's token authenticates it as your workspace. Inject it as an environment variable, store it the same way you store other secrets, and rotate it if a host is decommissioned.+- **Egress only.** Because the connection is outbound, an egress firewall that blocks `api.openstatus.dev:443` will silently stop the probe from running checks. The probe will appear "connected" briefly and then go quiet.++## Current limitations++Private locations are in **beta**. Two capabilities are not yet wired up:++- **No automatic incidents.** A failing check from a private location does not currently open an incident or fire notifications. If you need alerting today, keep at least one public location on the monitor.+- **Not displayed on public status pages.** Monitors assigned only to private locations won't appear on a public status page as a monitor-linked component.++Both are tracked and expected to land — when they do, the [private location reference](/docs/reference/private-location) will reflect the change.++## Next steps++- **[Set up a private location](/docs/tutorial/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.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.mdxnew file mode 100644index 000000000..506b4953d--- /dev/null+++ b/apps/web/src/content/pages/docs/concept/probes-and-locations.mdx@@ -0,0 +1,60 @@+---+category: Concepts+title: Probes, Locations, and Regions+description: "Three words that look interchangeable but aren't — what each one means in openstatus and how they fit together."+---++Reading the openstatus docs, you'll hit three words that seem to mean the same thing — **probe**, **location**, and **region**. They don't. Each one names a different layer of the same system, and knowing which is which makes the rest of the configuration surface much easier to navigate.++## The three terms in one sentence++> A **probe** runs in a **region** and exposes itself to you as a **location** you can assign to a monitor.++That's the relationship in shorthand. The rest of this page unpacks each term and explains why the distinction matters when you're configuring monitors or debugging where a check came from.++## Probe++A **probe** is the software that actually performs a check. It opens the TCP connection, sends the HTTP request, resolves the DNS record, measures the timing — and reports the result back. There are two kinds:++- **Public probes.** Operated by openstatus, deployed across Fly.io, Railway, and Koyeb regions. You don't manage them.+- **Private probes.** A container image (`ghcr.io/openstatushq/probe:latest`) you run on your own infrastructure. See [Understanding Private Locations](/docs/concept/private-locations).++In day-to-day usage you rarely interact with the "probe" abstraction directly — you assign a *location* to a monitor, and the location decides which probe runs the check. The word matters mostly when you're reading debug output, opening a support ticket, or deploying a private location.++## Region++A **region** is a physical-ish place where probes run. For openstatus public probes, regions map onto cloud-provider regions: Fly.io's `fra` (Frankfurt), Railway's `europe-west4-drams3a`, Koyeb's regions, and so on.++A region is an attribute of a probe, not something you configure directly on a monitor. Two facts follow from that:++- The list of regions changes when openstatus adds or removes provider capacity. The canonical list lives on the [location reference page](/docs/reference/location), which also documents the public IPv4/IPv6 addresses for each region you might need to allowlist.+- IP behaviour follows the underlying provider. Fly.io regions expose both IPv4 and IPv6, Railway is IPv4-only, Koyeb has no static IPs. If you allowlist by IP, this matters.++## Location++A **location** is what you assign to a monitor. It's the user-facing handle that points at one or more probes in a region. Two flavours:++- **Public locations.** One per public region. Selecting `fly-fra` on a monitor means "run this check from a public probe in Frankfurt."+- **Private locations.** Created by you. A private location has a name, a token, and a set of attached monitors. The probe(s) you deploy with that token form the location.++When a monitor runs, the assigned locations determine where the check fans out to. Selecting three locations means three independent checks per cron tick — one per location — each contributing its own latency and status to the monitor's results.++## Putting it together++| Layer | Owned by | You configure it directly? |+| --- | --- | --- |+| Region | Cloud provider | No — it's a property of the underlying infra |+| Probe | openstatus (public) or you (private) | Indirectly, via the location |+| Location | You | **Yes** — this is what you attach to a monitor |++Three quick scenarios make the distinction concrete:++- **Adding global coverage.** You attach `fly-iad`, `fly-fra`, and `fly-syd` *locations* to a monitor. Each one represents a public *probe* running in the matching Fly.io *region*. You don't pick a probe directly.+- **Allowlisting on a firewall.** You need IPs, which are a *region* attribute. Look them up in [Location Reference](/docs/reference/location). The location names like `fly-fra` are the shorthand you'd grep for.+- **Monitoring an internal API.** No public region can reach your VPC, so you create a private *location*, deploy a private *probe* with its token, and pin the monitor to that location. The "region" is just wherever you happened to deploy the container.++## 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.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.mdxindex 90c390f2a..215d31ad2 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@@ -19,107 +19,107 @@ This works for small teams with few monitors, but doesn't scale.**Monitoring as Code** treats your monitoring configuration the same way you treat your application code: as text files that can be versioned, reviewed, and deployed through automated pipelines.-Instead of clicking buttons, you define monitors in YAML:+Instead of clicking buttons, you declare monitors, status pages, and notifications in Terraform — and apply them with the same workflow your team already uses for the rest of your infrastructure.-Uptime monitoring is a vital part of any robust system, ensuring your services are online and available to users. Historically, this has involved manually configuring monitors through a web interface, which can be tedious and prone to human error. Uptime Monitoring as Code changes this by treating your monitoring configurations like any other part of your application-as code.+## Why use monitoring as code?+This approach offers significant advantages:-## Why Use Uptime Monitoring as Code?+- **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.-This approach offers significant advantages:+- **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++We publish an official [Terraform provider](https://registry.terraform.io/providers/openstatusHQ/openstatus/latest) that lets you manage your entire openstatus workspace declaratively — monitors, status pages, component groups, notifications, and maintenance windows.++Here's what a minimal `main.tf` looks like:++```terraform+terraform {+ required_providers {+ openstatus = {+ source = "openstatusHQ/openstatus"+ version = "~> 0.1"+ }+ }+}++provider "openstatus" {+ api_token = var.openstatus_api_token+}-- **Version Control:** By defining your monitors in a YAML file, you can track every change, rollback to previous versions, and see who made which modifications using tools like Git. This is crucial for auditing and troubleshooting.--- **Automation and Consistency:** Your monitoring setup can be part of your automated deployment pipeline. When you deploy a new service, its monitors are created automatically, ensuring consistency across your entire infrastructure. This eliminates the risk of forgetting to set up monitoring for a new service.--- **Collaboration:** A code-based approach simplifies collaboration among teams. A developer can create a new monitor definition in the YAML file and submit it for peer review, just as they would with any other code change. This promotes a shared understanding of your system's health.--- **Scalability:** Manually setting up hundreds of monitors is a nightmare. With a code-based approach, you can programmatically generate configurations for a large number of services, making it easy to scale your monitoring as your infrastructure grows.--- **Simplified Auditing:** Since the entire configuration is in a file, it's easy to see the current state of your monitors at a glance. You don't have to navigate through multiple screens in a web UI.---## How It Works with openstatus-- We offer the use ofa simple, human-readable YAML file to define all uptime monitors. This file serves as the single source of truth for your monitoring setup. You define each monitor with its URL, expected status code, and other parameters.--Here’s an example of what your `openstatus.yaml` file might look like:--```yaml-# openstatus.yaml-# yaml-language-server: $schema=https://www.openstatus.dev/schema.json-uptime-monitor:- name: "Uptime Monitor"- description: "Uptime monitoring example"- frequency: "10m"- active: true- regions:- - iad- - ams- - syd- - jnb- - gru- retry: 3- kind: http- request:- url: https://openstat.us- method: GET- headers:- User-Agent: openstatus- assertions:- - kind: statusCode- compare: eq- target: 200--graphql-monitor:- name: "Graphql"- description: "GitHub GraphQL API"- frequency: "10m"- active: true- regions:- - iad- - ams- - syd- - jnb- - gru- retry: 3- kind: http- request:- url: https://api.github.com/graphql- method: POST- headers:- User-Agent: openstatus- Authorization: Bearer YOUR_TOKEN_HERE- body: |- {- "query": "query { viewer { login }}"- }+resource "openstatus_http_monitor" "api" {+ name = "API Health Check"+ description = "Monitors the main API health endpoint."+ url = "https://api.example.com/health"+ periodicity = "5m"+ method = "GET"+ active = true+ regions = ["fly-iad", "fly-ams", "fly-syd"]++ status_code_assertions {+ target = 200+ comparator = "eq"+ }++ body_assertions {+ target = "ok"+ comparator = "contains"+ }+}++resource "openstatus_notification" "slack" {+ name = "Slack Alerts"+ provider_type = "slack"+ monitor_ids = [openstatus_http_monitor.api.id]++ slack {+ webhook_url = var.slack_webhook_url+ }+}```-### Making Changes with the CLI+### Applying changes-Once your `openstatus.yaml` file is ready, you use our [command-line interface (CLI)](/docs/tutorial/get-started-with-openstatus-cli) to apply the changes. The CLI compares your local configuration with the current state of your monitors and applies only the necessary changes creating new monitors, updating existing ones, or deleting those no longer defined.+Once your configuration is ready, the standard Terraform workflow takes over. `terraform plan` shows you a diff against the live state; `terraform apply` reconciles it.-**Common CLI Commands:**+```bash+terraform init # Download the openstatus provider+terraform plan # Preview what will change+terraform apply # Apply the changes+```-- `openstatus monitors apply`: Applies the changes defined in your `openstatus.yaml` file.-- `openstatus monitors import`: Import the monitors from your dashboard to a new `openstatus.yaml` file.+Terraform only modifies what changed — updates are in place, with no downtime for unaffected monitors.++### Adopting it for an existing workspace++If you already have monitors and status pages set up in the dashboard, you don't have to rewrite them by hand. The openstatus CLI can export your workspace into ready-to-use `.tf` files:++```bash+openstatus terraform generate+```-By integrating this **Uptime Monitoring as Code** workflow into your development lifecycle, you can achieve a more reliable, consistent, and scalable system. It's about moving from manual clicks to automated, version-controlled operations.+From there, import the resources into Terraform state and you're managing the existing setup as code.## Best practices1. **Start simple**: Begin with a few monitors, expand as you learn-2. **Use templates**: Create reusable patterns for common monitor types-3. **Environment variables**: Use secrets management for tokens and sensitive data-4. **Review changes**: Always review diffs before applying+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 applying5. **Document decisions**: Use commit messages to explain "why"## Next stepsReady to implement monitoring as code?-- **[Get Started with CLI](/docs/tutorial/get-started-with-openstatus-cli)** - Install and configure the CLI+- **[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-- **[CLI Reference](/docs/reference/cli-reference)** - Complete command documentation-- **[YAML Examples](https://github.com/openstatusHQ/cli-template)** - Sample configurationsdiff --git a/apps/web/src/content/pages/docs/reference/overview.mdx b/apps/web/src/content/pages/docs/reference/overview.mdxnew file mode 100644index 000000000..678845808--- /dev/null+++ b/apps/web/src/content/pages/docs/reference/overview.mdx@@ -0,0 +1,48 @@+---+category: Reference+title: Reference Overview+description: "Technical specifications for openstatus monitors, status pages, notifications, locations, and the CLI, MCP, and Terraform integrations."+---++This section is the source of truth for openstatus configuration. Use it to look up exact field names, types, defaults, and behaviour — not to learn how to do something. For task-oriented walkthroughs, see the [how-to guides](/docs/guides/getting-started); for learning paths, see the [tutorials](/docs/tutorial/getting-started).++## Monitors++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.++## 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.+- **[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.+- **[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.++## 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.++## 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.diff --git a/apps/web/src/content/pages/docs/tutorial/your-first-notification.mdx b/apps/web/src/content/pages/docs/tutorial/your-first-notification.mdxnew file mode 100644index 000000000..916535c28--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/your-first-notification.mdx@@ -0,0 +1,91 @@+---+category: Tutorials+title: Wire Up Your First Notification+description: "Send your first alert from openstatus — create a notification channel, attach it to a monitor, and confirm an alert lands."+---++## What you'll learn++| | |+|---|---|+| **Time** | ~5 minutes |+| **Level** | Beginner |+| **Prerequisites** | openstatus account, one monitor |++In this tutorial, you'll wire up a notification channel and attach it to a monitor so you actually get alerted when something breaks. A monitor without a notification channel is a tree falling in the woods — the data is there, but no one hears about it until they open the dashboard. By the end you'll have a working alert path you can verify with a single test endpoint.++This tutorial uses **email** because it's the channel that needs the least setup. The wiring is the same for Slack, Discord, PagerDuty, Telegram, webhooks, and every other channel — only the channel-specific config field changes. The [notification reference](/docs/reference/notification) lists each channel's exact configuration.++### Prerequisites++- An openstatus account ([openstatus.dev](https://www.openstatus.dev))+- At least one monitor (see [Create Your First Monitor](/docs/tutorial/how-to-create-monitor))+- An email address you can read right now++### What you'll build++By the end of this tutorial, you'll have:++- An email notification channel created in openstatus+- The channel attached to one of your monitors+- A clear understanding of what triggers a notification and what doesn't++## 1. Create a notification channel++Navigate to **Settings** > **Notification Channels** in the dashboard and click **Create Notification Channel**.++Pick **Email** as the channel type and fill in two fields:++- **Name** — how the channel shows up in the dashboard. Use something self-descriptive like `On-call email` or `Engineering alerts`. You'll see this name on every monitor it's attached to.+- **Email address** — the recipient. Use an address you can check right now so you can verify the alert arrives.++Save the channel. It's now created but not yet attached to anything — no notifications will fire.++<Aside>+Channels are workspace-scoped, not monitor-scoped. One channel can be attached to many monitors, and one monitor can fan out to many channels. Treat channels like routing targets ("on-call", "platform team", "noisy-staging-channel") rather than per-monitor settings.+</Aside>++## 2. Attach the channel to a monitor++Open one of your monitors and go to its **Notifications** tab. Select the channel you just created and save.++That's the wiring done. From now on, when the monitor transitions into a failing state — `down` or `degraded` — your channel will receive a notification. When the monitor recovers, you'll get a recovery notification too.++**Checkpoint:** the monitor's notification tab should now show the channel listed. If it doesn't appear in the dropdown, refresh the page once — newly created channels can take a moment to propagate to the monitor settings.++## 3. Trigger a test alert++The fastest way to see a real notification is to point a monitor at an endpoint that's guaranteed to fail, and let it run for a few checks.++Create (or temporarily reconfigure) a monitor with these settings:++- **URL:** `https://openstat.us/500` — a public test endpoint that always responds `500 Internal Server Error`.+- **Frequency:** `1 minute` — so you don't have to wait long.+- **Notification channel:** the one you just created.++Wait a couple of minutes. Once enough consecutive checks have failed to cross the trigger threshold (50% of recent checks — see [Incident Reference](/docs/reference/incident)), openstatus opens an incident and fires the notification.++Check the inbox you used in step 1. You should see an alert with the monitor name, the URL, the status code, and a link back to the dashboard. Delete the test monitor — or point it back at a real URL — once you've confirmed the email arrived.++<Aside type="tip">+The same trigger threshold that fires the alert also gates *recovery*. If you point the test monitor back at a healthy URL, you'll get a second email confirming the monitor is up again, once enough checks have passed.+</Aside>++## What you've accomplished++- Created an email notification channel+- Attached it to a monitor and confirmed an alert lands end-to-end+- Learned that channels are workspace-scoped and reusable across monitors+- Seen first-hand how the trigger threshold delays the first alert (this is the feature, not a bug — it prevents flapping)++## What's next?++Now you have one alert path working. From here:++- **[Set up the Slack agent](/docs/tutorial/how-to-setup-slack-agent)** — turn alerts into a two-way conversation where you can also create and resolve incidents from Slack.+- **[Open your first status report](/docs/tutorial/your-first-status-report)** — when an alert fires, communicate the incident to your users.++### Learn more++- **[Notification Channels Reference](/docs/reference/notification)** — every channel type, its config fields, and (for webhooks) the payload schema.+- **[Incident Reference](/docs/reference/incident)** — exactly what triggers a notification and the lifecycle states an incident goes through.diff --git a/apps/web/src/content/pages/docs/tutorial/your-first-status-report.mdx b/apps/web/src/content/pages/docs/tutorial/your-first-status-report.mdxnew file mode 100644index 000000000..058040289--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/your-first-status-report.mdx@@ -0,0 +1,101 @@+---+category: Tutorials+title: Publish Your First Status Report+description: "Open, update, and resolve a status report from the openstatus dashboard — the four-state workflow your users will see during an incident."+---++## What you'll learn++| | |+|---|---|+| **Time** | ~10 minutes |+| **Level** | Beginner |+| **Prerequisites** | openstatus account, one status page |++In this tutorial, you'll publish a status report end-to-end: open it, post two updates as your investigation progresses, and resolve it. A status report is what your users actually read during an incident — the trace of "we noticed, we found it, we fixed it, we're done." Doing one in calm conditions, before you need it under pressure, is the cheapest way to learn the workflow.++Status reports follow a four-state lifecycle: **investigating → identified → monitoring → resolved**. You'll walk through all four states in one short exercise.++### Prerequisites++- An openstatus account ([openstatus.dev](https://www.openstatus.dev))+- A status page with at least one component (see [Create a Status Page](/docs/tutorial/how-to-create-status-page))+- A few minutes — the tutorial walks all four states in a single sitting++### What you'll build++By the end of this tutorial, you'll have:++- An incident report visible on your status page, then archived as resolved+- A working mental model of the four states and when to use each+- Practical experience with the update cadence — what to write, when to ship it++<Aside>+The dashboard isn't the only way to manage status reports. The [openstatus CLI](/docs/reference/cli-reference#status-report-command) drives the same workflow from a terminal — handy during a real outage when you don't want to context-switch. This tutorial sticks to the dashboard because the goal is to learn the lifecycle, not the tooling.+</Aside>++## 1. Open the report++Navigate to your status page in the dashboard and open the **Status Reports** tab. Click **Create Status Report**.++Fill in three fields:++- **Title** — short and specific. `API elevated latency` is better than `API issue`. Users skim titles; tell them which surface and what they should expect.+- **Status** — start with `investigating`. You've noticed the problem and are looking into it.+- **Message** — one or two sentences. What are you seeing, who's affected, are you actively on it? Don't speculate about root cause yet — that comes in the next update.+- **Affected components** — select the component(s) the incident touches. This drives the visual state on the public status page (the green bar turns yellow or red next to those components).++Save the report. If your status page subscribers are enabled and your page is public, this is the moment they get the first notification — make sure the message is one you'd be okay sending to every subscriber.++**Checkpoint:** open your status page in a new tab. You should see a banner with the title, the `Investigating` label, and the affected components highlighted.++## 2. Post an "identified" update++Imagine ten minutes have passed and you've found the root cause. Back in the dashboard, open the report and click **Add update**.++- **Status** — change to `identified`.+- **Message** — name the cause in user-facing language. `Root cause is a misconfigured cache TTL on the API tier. Rolling back the change now.` is the right register: specific enough to be credible, generic enough not to leak internal terminology.++Save. The update appears on the status page as a new timeline entry under the original one.++<Aside type="tip">+"Identified" doesn't mean "fixed" — it means you know what's wrong. Posting it as soon as you actually know is more valuable than a perfect, polished message ten minutes later. Users would rather see "we know what it is" than radio silence.+</Aside>++## 3. Post a "monitoring" update++The fix is deployed and you're watching the metrics recover. Add another update:++- **Status** — `monitoring`.+- **Message** — describe what you deployed and what you're watching for. `Cache TTL change has been reverted. Response times are recovering. Continuing to monitor for the next 15 minutes.` sets an expectation, which is what users want from this state.++This is the most-skipped state in real life — teams jump straight from `identified` to `resolved`. Don't. The `monitoring` state is your buffer: if recovery doesn't hold, you can flip the status back without having to reopen a "resolved" report. Use it.++## 4. Resolve the report++Recovery has held. Add the final update:++- **Status** — `resolved`.+- **Message** — close the loop. `Response times have been stable for 15 minutes. Incident resolved. A post-incident review will be published in the engineering blog.` is a good template — it confirms the state, gives a time window, and (optionally) points to what comes next.++Save. The report is now archived. On the status page it moves out of the active banner into the history section, and the affected components flip back to their healthy state.++**Checkpoint:** open the status page once more. The active incident banner should be gone, the components should be green, and the report should be visible under the incident history.++## What you've accomplished++- Walked a status report through all four lifecycle states+- Practiced the kind of language each state calls for — neutral, specific, time-bounded+- Built the muscle memory you actually want before a real incident, not during one++## What's next?++- **[Set up the Slack agent](/docs/tutorial/how-to-setup-slack-agent)** — create and update status reports by talking to the openstatus bot from Slack.+- **[Wire up your first notification](/docs/tutorial/your-first-notification)** — make sure you find out about an incident before your users do.++### Learn more++- **[Status Report Reference](/docs/reference/status-report)** — every field on a status report and what the four states mean precisely.+- **[Incident Reference](/docs/reference/incident)** — how openstatus auto-detects incidents from monitor failures (the trigger side of the same workflow).+- **[Building Trust with Status Pages](/docs/concept/best-practices-status-page)** — the *why* behind the four-state cadence.+- **[CLI Reference — status-report](/docs/reference/cli-reference#status-report-command)** — the same workflow from a terminal.