Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
docs: new guides (#2245)
Thibault Le Ouay0e61839359e4
diff --git a/apps/web/next.config.ts b/apps/web/next.config.tsindex 679253226..dbc034aa9 100644--- a/apps/web/next.config.ts+++ b/apps/web/next.config.ts@@ -177,7 +177,12 @@ const nextConfig: NextConfig = {},{source: "/docs/tutorial/how-to-manage-openstatus-with-terraform-cli",- destination: "/docs/guides/how-to-manage-openstatus-with-terraform-cli",+ destination: "/docs/guides/how-to-manage-openstatus-with-terraform",+ permanent: true,+ },+ {+ source: "/docs/guides/how-to-manage-openstatus-with-terraform-cli",+ destination: "/docs/guides/how-to-manage-openstatus-with-terraform",permanent: true,},{diff --git a/apps/web/src/content/docs.config.ts b/apps/web/src/content/docs.config.tsindex 4ddee420b..bcfe5a9e1 100644--- a/apps/web/src/content/docs.config.ts+++ b/apps/web/src/content/docs.config.ts@@ -89,6 +89,10 @@ export const docsNav: DocsNavSection[] = [slug: "tutorial/get-started-with-openstatus-cli",label: "Get Started with openstatus CLI",},+ {+ slug: "tutorial/manage-status-reports-cli",+ label: "Manage Status Reports from the CLI",+ },],},{@@ -141,8 +145,8 @@ export const docsNav: DocsNavSection[] = [label: "How to Connect openstatus to Claude Code",},{- slug: "guides/how-to-manage-openstatus-with-terraform-cli",- label: "How to Manage Your openstatus Stack with Terraform and the CLI",+ slug: "guides/how-to-manage-openstatus-with-terraform",+ label: "How to Manage Your openstatus Stack with Terraform",},{slug: "guides/how-to-create-private-location",diff --git a/apps/web/src/content/pages/changelog/terraform-provider-update.mdx b/apps/web/src/content/pages/changelog/terraform-provider-update.mdxindex b97648d20..96283a57f 100644--- a/apps/web/src/content/pages/changelog/terraform-provider-update.mdx+++ b/apps/web/src/content/pages/changelog/terraform-provider-update.mdx@@ -61,7 +61,7 @@ provider "openstatus" {}```-Check out the [Terraform provider reference](https://www.openstatus.dev/docs/reference/terraform/) for full documentation and examples, or follow the [guide](https://www.openstatus.dev/docs/guides/how-to-manage-openstatus-with-terraform-cli) to set up your monitoring stack from scratch.+Check out the [Terraform provider reference](https://www.openstatus.dev/docs/reference/terraform/) for full documentation and examples, or follow the [guide](https://www.openstatus.dev/docs/guides/how-to-manage-openstatus-with-terraform) to set up your monitoring stack from scratch.## Thank youdiff --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 e8890a273..bc715f54a 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@@ -114,6 +114,6 @@ From there, import the resources into Terraform state and you're managing the ex## Next steps-- **[Manage openstatus with Terraform](/docs/guides/how-to-manage-openstatus-with-terraform-cli)** — end-to-end guide.+- **[Manage openstatus with Terraform](/docs/guides/how-to-manage-openstatus-with-terraform)** — 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/guides/how-to-manage-openstatus-with-terraform-cli.mdx b/apps/web/src/content/pages/docs/guides/how-to-manage-openstatus-with-terraform.mdxsimilarity index 54%rename from apps/web/src/content/pages/docs/guides/how-to-manage-openstatus-with-terraform-cli.mdxrename to apps/web/src/content/pages/docs/guides/how-to-manage-openstatus-with-terraform.mdxindex fd94ff30e..1325d08f9 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.mdx@@ -1,26 +1,20 @@---category: Guides-title: Manage Your openstatus Stack with Terraform and the CLI-description: "Use Terraform to manage monitors, status pages, and notifications as code — and the openstatus CLI to handle incident status reports."+title: Manage Your openstatus Stack with Terraform+description: "Use Terraform to manage monitors, status pages, and notifications as code — version-controlled, peer-reviewed, and reproducible."----| | ||---|---|-| **Time** | ~20 minutes |+| **Time** | ~15 minutes || **Level** | Intermediate |-| **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 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** | openstatus account, [Terraform](https://developer.hashicorp.com/terraform/install) installed, API token from workspace settings |-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.+In this guide, you'll manage your openstatus infrastructure as code with the official [Terraform provider](https://registry.terraform.io/providers/openstatusHQ/openstatus/latest) — monitors, notification channels, status pages, component groups. These are long-lived resources that change infrequently and benefit from code review, version control, and `terraform plan`.-## Part 1 — infrastructure with Terraform+For operational, time-sensitive work — opening and updating status reports during an incident — see the [status reports from the CLI tutorial](/docs/tutorial/manage-status-reports-cli). The two tools are complementary; pick the right one for the job.-### Step 1 — set up the provider+## Step 1 — set up the providerCreate a new directory for your Terraform configuration and add a `main.tf` file:@@ -44,7 +38,7 @@ variable "openstatus_api_token" {}```-Initialize the provider:+Initialise the provider:```bashterraform init@@ -52,7 +46,7 @@ terraform init<Aside>Set the token via an environment variable to avoid passing it on every run: `export TF_VAR_openstatus_api_token="your-token"`</Aside>-### Step 2 — define your monitors+## Step 2 — define your monitorsAdd monitors to your `main.tf`. We'll create three types — HTTP, TCP, and DNS.@@ -120,7 +114,7 @@ resource "openstatus_dns_monitor" "domain" {}```-### Step 3 — add notifications+## Step 3 — add notificationsWire up a Slack notification so you get alerted when monitors fail:@@ -146,9 +140,9 @@ resource "openstatus_notification" "slack" {<Aside>The provider supports 12 notification types including PagerDuty, Discord, Email, OpsGenie, and webhooks. See the [Terraform provider reference](/docs/reference/terraform#openstatus_notification) for all options.</Aside>-### 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:+Define a public status page and organise monitors into component groups:```terraformresource "openstatus_status_page" "main" {@@ -190,7 +184,7 @@ resource "openstatus_status_page_component" "db_component" {}```-### Step 5 — plan and apply+## Step 5 — plan and applyPreview the changes Terraform will make:@@ -204,11 +198,12 @@ You should see all resources listed as "will be created". Apply them:terraform apply```-**Checkpoint:** After applying, verify everything is live:-- Open your openstatus dashboard — your monitors should appear in the Monitors tab-- Visit your status page at `https://<your-slug>.openstatus.dev` — you should see your component groups and monitors+**Checkpoint:** after applying, verify everything is live:-### Step 6 — update your infrastructure+- Open your openstatus dashboard — your monitors should appear in the Monitors tab.+- Visit your status page at `https://<your-slug>.openstatus.dev` — you should see your component groups and monitors.++## Step 6 — update your infrastructureTo make changes, edit your `.tf` files and re-apply. For example, add a new region to the API monitor:@@ -225,7 +220,7 @@ terraform apply # Apply the updateTerraform only modifies what changed — the monitor gets updated in place, no downtime.-### Step 7 — import existing resources+## Step 7 — import existing resourcesIf you already have monitors, status pages, or notifications created in the dashboard, you can generate the corresponding Terraform configuration automatically using the CLI:@@ -245,103 +240,9 @@ terraform import openstatus_notification.slack <notification-id>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--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--Make sure your API token is set:--```bash-export OPENSTATUS_API_TOKEN="your-api-token"-```--Verify your setup:--```bash-openstatus whoami-```--### Step 9 — create a status report--When an incident starts, create a status report and link it to your status page and affected components:--```bash-openstatus status-report create \- --title "API Elevated Latency" \- --status investigating \- --message "We are investigating increased response times on the API." \- --page-id <page-id> \- --component-ids <api-component-id> \- --notify-```--Key flags:-- **`--status`**: The initial incident state — `investigating`, `identified`, `monitoring`, or `resolved`.-- **`--page-id`**: Links the report to your status page so visitors can see it.-- **`--component-ids`**: Marks specific components as affected (comma-separated for multiple).-- **`--notify`**: Sends a notification to all status page subscribers.--<Aside>Find your page and component IDs with `openstatus status-page list` and `openstatus status-page info <page-id>`.</Aside>--### Step 10 — post updates as you investigate+## When to reach for Terraform vs the CLI-As the incident progresses, add updates to the report. Each update changes the status and adds a timestamped message:--```bash-# Root cause identified-openstatus status-report add-update <report-id> \- --status identified \- --message "Root cause identified: a misconfigured cache TTL is causing stale responses." \- --notify--# Fix deployed, monitoring-openstatus status-report add-update <report-id> \- --status monitoring \- --message "Fix deployed to production. Monitoring response times for recovery."--# Incident resolved-openstatus status-report add-update <report-id> \- --status resolved \- --message "Response times have returned to normal. Incident resolved." \- --notify-```--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--List recent incidents:--```bash-# All reports-openstatus status-report list--# Only active incidents-openstatus status-report list --status investigating--# Detailed view of a specific report-openstatus status-report info <report-id>-```--Update report metadata (title, affected components):--```bash-openstatus status-report update <report-id> \- --title "API Elevated Latency — Cache Misconfiguration" \- --component-ids <api-component-id>,<db-component-id>-```--Delete a report (e.g., created by mistake):--```bash-openstatus status-report delete <report-id>-```--## Putting it all together--Here's how the two tools fit into your workflow:+Terraform is right for **long-lived infrastructure**. The CLI is right for **operational, time-sensitive work** during an incident.| Task | Tool | Why || :--- | :--- | :--- |@@ -349,38 +250,19 @@ Here's how the two tools fit into your workflow:| Create/update status pages | Terraform | Long-lived infrastructure, managed as code || Configure notifications | Terraform | Declarative, easy to audit || Report an incident | CLI | Fast, imperative, time-sensitive |-| Post incident updates | CLI | Happens in real-time during an outage |+| Post incident updates | CLI | Happens in real time during an outage || Trigger a monitor check | CLI | On-demand operational task |-## CLI commands cheat sheet--| Command | Description |-| :--- | :--- |-| `openstatus whoami` | Verify your API token and workspace |-| `openstatus status-report create` | Create a new incident report |-| `openstatus status-report add-update <id>` | Add a status update to an incident |-| `openstatus status-report update <id>` | Update report metadata (title, components) |-| `openstatus status-report list` | List all status reports |-| `openstatus status-report list --status investigating` | Filter by incident status |-| `openstatus status-report info <id>` | View a report's full timeline |-| `openstatus status-report delete <id>` | Delete a status report |-| `openstatus monitors list` | List all monitors |-| `openstatus monitors info <id>` | View monitor details and metrics |-| `openstatus monitors trigger <id>` | Trigger an immediate check |-| `openstatus status-page list` | List all status pages |-| `openstatus status-page info <id>` | View status page details and component IDs |-| `openstatus terraform generate` | Export workspace resources to Terraform `.tf` files |-## What you've accomplished- 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+- Imported existing resources into Terraform state## What's next+- **[Manage status reports from the CLI](/docs/tutorial/manage-status-reports-cli)** — the operational counterpart to this guide.- **[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.@@ -388,8 +270,6 @@ Here's how the two tools fit into your workflow:### 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.diff --git a/apps/web/src/content/pages/docs/tutorial/manage-status-reports-cli.mdx b/apps/web/src/content/pages/docs/tutorial/manage-status-reports-cli.mdxnew file mode 100644index 000000000..90466c50a--- /dev/null+++ b/apps/web/src/content/pages/docs/tutorial/manage-status-reports-cli.mdx@@ -0,0 +1,146 @@+---+category: Tutorials+title: Manage Status Reports from the CLI+description: "Open, update, and resolve status reports from the terminal during an incident — the operational counterpart to managing your stack as code."+---++| | |+|---|---|+| **Time** | ~10 minutes |+| **Level** | Intermediate |+| **Prerequisites** | openstatus account, a status page with at least one component (see [Create a status page](/docs/tutorial/create-your-first-status-page)), [openstatus CLI](/docs/tutorial/get-started-with-openstatus-cli) installed |++In this tutorial, you'll drive the whole status report lifecycle from your terminal: open a report, post updates as you investigate, and resolve it. The CLI is the right tool here — status reports are operational and time-sensitive. You create one when an incident is happening, not when you're planning infrastructure. The CLI is fast, imperative, and scriptable from CI; the dashboard and Terraform are wrong for this job.++If you haven't published a status report before, you might also want to walk through the [dashboard version of this workflow](/docs/tutorial/your-first-status-report) first to internalise the four-state lifecycle.++## 1. Configure the CLI++Make sure your API token is set:++```bash+export OPENSTATUS_API_TOKEN="your-api-token"+```++Verify your setup:++```bash+openstatus whoami+```++You should see your workspace name. If you get an authentication error, the token is missing or wrong — check the [CLI tutorial](/docs/tutorial/get-started-with-openstatus-cli) for the setup steps.++## 2. Find your page and component IDs++Status report commands need the IDs of the status page and the components the incident affects. Look them up once and save them somewhere:++```bash+# List your status pages+openstatus status-page list++# Show the page details, including component IDs+openstatus status-page info <page-id>+```++<Aside>Keep these IDs in a script or your shell history — during a real incident you don't want to be hunting for them. Many teams wrap the report commands in a small shell function that already knows the IDs.</Aside>++## 3. Open the report++When the incident starts, create the report with an initial `investigating` status and notify subscribers:++```bash+openstatus status-report create \+ --title "API Elevated Latency" \+ --status investigating \+ --message "We are investigating increased response times on the API." \+ --page-id <page-id> \+ --component-ids <api-component-id> \+ --notify+```++Key flags:++- **`--status`** — the initial state. `investigating`, `identified`, `monitoring`, or `resolved`.+- **`--page-id`** — links the report to your status page so visitors can see it.+- **`--component-ids`** — marks specific components as affected (comma-separated for multiple).+- **`--notify`** — sends a notification to all status page subscribers.++The command returns the new report ID. Save it — every update command needs it.++**Checkpoint:** open your status page in a browser. You should see a banner with the title, the `Investigating` label, and the affected components highlighted.++## 4. Post updates as you investigate++As the incident progresses, append updates. Each update changes the status and adds a timestamped message:++```bash+# Root cause identified+openstatus status-report add-update <report-id> \+ --status identified \+ --message "Root cause identified: a misconfigured cache TTL is causing stale responses." \+ --notify++# Fix deployed, monitoring+openstatus status-report add-update <report-id> \+ --status monitoring \+ --message "Fix deployed to production. Monitoring response times for recovery."++# Incident resolved+openstatus status-report add-update <report-id> \+ --status resolved \+ --message "Response times have returned to normal. Incident resolved." \+ --notify+```++Each update appears on your public status page as a new timeline entry under the original report, giving users a clear visibility into what happened and when.++<Aside type="tip">`--notify` is per-update, not per-report. Use it on the opening report, on `identified` once you have something concrete to say, and on `resolved`. Skip it on intermediate `monitoring` updates so you don't spam subscribers while you watch the metrics recover.</Aside>++## 5. Review and manage reports++List recent incidents:++```bash+# All reports+openstatus status-report list++# Only active incidents+openstatus status-report list --status investigating++# Detailed view of a specific report+openstatus status-report info <report-id>+```++Update report metadata (title, affected components) without posting a new public update:++```bash+openstatus status-report update <report-id> \+ --title "API Elevated Latency — Cache Misconfiguration" \+ --component-ids <api-component-id>,<db-component-id>+```++Delete a report (e.g., one created by mistake):++```bash+openstatus status-report delete <report-id>+```++## What you've accomplished++- Opened a status report from the terminal and published an initial update to subscribers+- Walked the report through all four lifecycle states with `add-update`+- Updated metadata after the fact without re-notifying subscribers+- Built the muscle memory you actually want before a real incident, not during one++## What's next++- **[Manage your stack with Terraform](/docs/guides/how-to-manage-openstatus-with-terraform)** — the infrastructure counterpart to this tutorial.+- **[Run synthetic tests in GitHub Actions](/docs/guides/how-to-run-synthetic-test-github-action)** — script the CLI into your CI/CD pipeline.+- **[Set up the Slack agent](/docs/guides/how-to-setup-slack-agent)** — drive the same workflow from Slack when you're already in a war-room channel.++### Learn more++- **[CLI reference](/docs/reference/cli-reference)** — every command, subcommand, and flag.+- **[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.