Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
feat: incident severity matrix builder + guide (#1892)
Maximilian Kaske30c3c6755ff2
diff --git a/TELEGRAM.md b/TELEGRAM.mddeleted file mode 100644index 75a9558d8..000000000--- a/TELEGRAM.md+++ /dev/null@@ -1,76 +0,0 @@-# Telegram Group Integration Technical Documentation--This document outlines the technical architecture, security measures, and configuration requirements for the Telegram bot integration in OpenStatus.--## Overview--The integration follows a two-step "QR Code" flow to securely link a Telegram group to an OpenStatus workspace:-1. **Phase 1 (Private Connection)**: Link a user's Telegram account to a workspace via a one-time token.-2. **Phase 2 (Group Addition)**: Detect when the bot is added to a group by that specific user.-------## Environment Variables--The following environment variables must be configured in both the dashboard and the API packages.--| Variable | Scope | Description |-| :--- | :--- | :--- |-| `TELEGRAM_BOT_TOKEN` | Backend | The API token provided by BotFather. Used for `getUpdates`. |-| `NEXT_PUBLIC_TELEGRAM_BOT_USERNAME` | Frontend & Backend | The username of the bot (without `@`). Used for QR links and identity verification. |-------## Technical Architecture--### 1. Token Management (Redis)-We use a **Unified Single-Key Strategy** to manage integration tokens.--- **Redis Key Pattern**: `telegram:workspace_token:${workspaceId}`-- **Storage**: Stores a plain 12-character random ID (generated using `nanoid(12)`).-- **Override Logic**: Only **one** active token is allowed per workspace at any time. Generating a new token automatically replaces the previous one.-- **Security Lifecycle**:- - **Expiry**: Tokens have a hard expiry of **30 minutes**.- - **One-Time Use**: The token is immediately deleted from Redis once the private chat connection (Phase 1) is successful.--### 2. Session Isolation & Stale Data Prevention-Telegram's `getUpdates` API returns updates from the last 24 hours. To prevent old messages from triggering new integrations, we implement **Timestamp Filtering**:--- **Session Start Time**: When the user clicks "Connect with QR", the frontend captures the current unix timestamp (`sessionStartTime`).-- **Query Filter**: The backend `getTelegramUpdates` query accepts a `since` parameter and skips any update with a `date < since`.-- **Reset Handling**: If a user resets the group ID, a new `sessionStartTime` is generated, ensuring only *subsequent* group additions are processed.--### 3. Update Processing Logic--#### Phase 1: Private Connection-- **Trigger**: User scans QR and sends `/start <token>`.-- **Verification**:- - Extract `token` from message text.- - Look up `storedRandomId` using the workspace ID from the request context.- - If `token === storedRandomId`, the connection is valid.- - The `privateChatId` is returned to the frontend.--#### Phase 2: Group Addition-- **Trigger**: User adds the bot to a group.-- **Verification**:- - Detects `new_chat_participant` or `new_chat_member` in the message object.- - **Bot Identity**: Verifies that `participant.username === NEXT_PUBLIC_TELEGRAM_BOT_USERNAME`.- - **Ownership**: Verifies that `message.from.id` matches the `privateChatId` linked in Phase 1.- - **Session**: Verifies `message.date >= since`.-------## UI Components--- **`FormTelegram`**: Orchestrates the flow, manages polling, and handles session state.-- **`TelegramQRConnection`**: Displays the QR code and the "Reset Group ID" button.-- **`TelegramQRCode`**: Generates the `t.me` URL with the appropriate `start` or `startgroup` parameters.-------## Group Reset Mechanism--Users can clear an accidental group connection using the **"Reset Group ID"** button.-1. Clears the `chatId` in the form.-2. Sets a new `sessionStartTime` (current time).-3. Polling continues, but will ignore the previous group addition because its timestamp is now older than the new session start time.diff --git a/apps/web/src/app/(landing)/play/checker/page.tsx b/apps/web/src/app/(landing)/play/checker/page.tsxindex eca16fac5..03eccb440 100644--- a/apps/web/src/app/(landing)/play/checker/page.tsx+++ b/apps/web/src/app/(landing)/play/checker/page.tsx@@ -6,6 +6,7 @@ import { BASE_URL, getPageMetadata } from "@/lib/metadata/shared-metadata";import {createJsonLDGraph,getJsonLDBreadcrumbList,+ getJsonLDFAQPage,getJsonLDWebPage,} from "@/lib/metadata/structured-data";import type { Metadata } from "next";@@ -45,6 +46,7 @@ export default async function Page(props: {{ name: "Playground", url: `${BASE_URL}/play` },{ name: page.metadata.title, url: `${BASE_URL}/play/checker` },]),+ getJsonLDFAQPage(page),]);return (diff --git a/apps/web/src/app/(landing)/play/curl/page.tsx b/apps/web/src/app/(landing)/play/curl/page.tsxindex 1dbb4c4ae..40ee31281 100644--- a/apps/web/src/app/(landing)/play/curl/page.tsx+++ b/apps/web/src/app/(landing)/play/curl/page.tsx@@ -4,6 +4,7 @@ import { BASE_URL, getPageMetadata } from "@/lib/metadata/shared-metadata";import {createJsonLDGraph,getJsonLDBreadcrumbList,+ getJsonLDFAQPage,getJsonLDWebPage,} from "@/lib/metadata/structured-data";import type { Metadata } from "next";@@ -24,6 +25,7 @@ export default function Page() {{ name: "Playground", url: `${BASE_URL}/play` },{ name: page.metadata.title, url: `${BASE_URL}/play/curl` },]),+ getJsonLDFAQPage(page),]);return (diff --git a/apps/web/src/app/(landing)/play/page.tsx b/apps/web/src/app/(landing)/play/page.tsxindex 179f210c9..1a7240360 100644--- a/apps/web/src/app/(landing)/play/page.tsx+++ b/apps/web/src/app/(landing)/play/page.tsx@@ -70,6 +70,11 @@ const PLAY = [description: "Explore themes for your status page",href: "https://themes.openstatus.dev",},+ {+ label: "Incident Severity Matrix Builder",+ description: "Classify incidents with deterministic, auditable rules",+ href: "/play/severity-matrix",+ },{label: "All Status Codes",description: "Explore all HTTP status codes",diff --git a/apps/web/src/app/(landing)/play/severity-matrix/client.tsx b/apps/web/src/app/(landing)/play/severity-matrix/client.tsxnew file mode 100644index 000000000..f21e0241d--- /dev/null+++ b/apps/web/src/app/(landing)/play/severity-matrix/client.tsx@@ -0,0 +1,445 @@+"use client";++import { Details } from "@/content/mdx-components/details";+import { Button } from "@openstatus/ui/components/ui/button";+import { Checkbox } from "@openstatus/ui/components/ui/checkbox";+import { Input } from "@openstatus/ui/components/ui/input";+import { Label } from "@openstatus/ui/components/ui/label";+import { Slider } from "@openstatus/ui/components/ui/slider";+import { useState } from "react";++type SeverityLevel = "SEV0" | "SEV1" | "SEV2" | "SEV3";++const SEV_ORDER = ["SEV0", "SEV1", "SEV2", "SEV3"] as const;++const SEVERITY_META = {+ SEV0: {+ label: "Critical",+ emoji: "π΄",+ responseTime: "15 minutes",+ statusPageLabel: "Major Outage",+ communication: "Immediate public update + all-hands",+ updateCadence: "Every 15 min",+ escalation: "VP Engineering + on-call",+ postmortem: "Required",+ },+ SEV1: {+ label: "High",+ emoji: "π ",+ responseTime: "30 minutes",+ statusPageLabel: "Partial Outage",+ communication: "Public update within 15 min",+ updateCadence: "Every 30 min",+ escalation: "Engineering lead",+ postmortem: "Required",+ },+ SEV2: {+ label: "Medium",+ emoji: "π‘",+ responseTime: "2 hours",+ statusPageLabel: "Degraded Performance",+ communication: "Status page update + ticket",+ updateCadence: "Every 2 hours",+ escalation: "Team lead",+ postmortem: "Required (team)",+ },+ SEV3: {+ label: "Low",+ emoji: "π’",+ responseTime: "1 business day",+ statusPageLabel: "Minor Issue",+ communication: "Internal ticket only",+ updateCadence: "Daily",+ escalation: "Assigned engineer",+ postmortem: "Optional",+ },+} satisfies Record<+ SeverityLevel,+ {+ label: string;+ emoji: string;+ responseTime: string;+ statusPageLabel: string;+ communication: string;+ updateCadence: string;+ escalation: string;+ postmortem: string;+ }+>;++const SEVERITY_BORDER: Record<SeverityLevel, string> = {+ SEV0: "border-red-500",+ SEV1: "border-orange-500",+ SEV2: "border-yellow-500",+ SEV3: "border-green-500",+};++const TEST_SCENARIOS = [+ {+ label: "DB Failover",+ usersAffected: 60,+ securityImpact: false,+ slaBreach: false,+ },+ {+ label: "API Auth Breach",+ usersAffected: 5,+ securityImpact: true,+ slaBreach: false,+ },+ {+ label: "CDN Degradation",+ usersAffected: 15,+ securityImpact: false,+ slaBreach: false,+ },+ {+ label: "Payment Timeout",+ usersAffected: 90,+ securityImpact: false,+ slaBreach: true,+ },+ {+ label: "CSS Regression",+ usersAffected: 5,+ securityImpact: false,+ slaBreach: false,+ },+] as const;++function classifySeverity(params: {+ usersAffected: number;+ securityImpact: boolean;+ slaBreach: boolean;+ thresholdCritical: number;+ thresholdHigh: number;+ thresholdMedium: number;+}): SeverityLevel {+ const {+ usersAffected,+ securityImpact,+ slaBreach,+ thresholdCritical,+ thresholdHigh,+ thresholdMedium,+ } = params;++ if (securityImpact) return "SEV0";++ let sev: SeverityLevel;+ if (usersAffected >= thresholdCritical) sev = "SEV0";+ else if (usersAffected >= thresholdHigh) sev = "SEV1";+ else if (usersAffected >= thresholdMedium) sev = "SEV2";+ else sev = "SEV3";++ // SLA modifier: upgrade one level if severity is below SEV1+ if (slaBreach && (sev === "SEV2" || sev === "SEV3")) {+ sev = SEV_ORDER[SEV_ORDER.indexOf(sev) - 1];+ }++ return sev;+}++function classifyReason(params: {+ usersAffected: number;+ securityImpact: boolean;+ slaBreach: boolean;+ thresholdCritical: number;+ thresholdHigh: number;+ thresholdMedium: number;+}): string {+ const {+ usersAffected,+ securityImpact,+ slaBreach,+ thresholdCritical,+ thresholdHigh,+ thresholdMedium,+ } = params;++ if (securityImpact) return "Security impact override";++ if (usersAffected >= thresholdCritical)+ return `β₯${thresholdCritical}% users affected`;+ if (usersAffected >= thresholdHigh) {+ // SLA breach doesn't affect SEV1+ β only upgrades SEV2/SEV3+ return `β₯${thresholdHigh}% users affected`;+ }+ if (usersAffected >= thresholdMedium) {+ if (slaBreach)+ return `β₯${thresholdMedium}% users affected + SLA breach (upgraded)`;+ return `β₯${thresholdMedium}% users affected`;+ }+ if (slaBreach)+ return `<${thresholdMedium}% users affected + SLA breach (upgraded)`;+ return `<${thresholdMedium}% users affected`;+}++type Values = {+ usersAffected: number;+ securityImpact: boolean;+ slaBreach: boolean;+ thresholdCritical: number;+ thresholdHigh: number;+ thresholdMedium: number;+};++const defaultValues: Values = {+ usersAffected: 15,+ securityImpact: false,+ slaBreach: false,+ thresholdCritical: 80,+ thresholdHigh: 50,+ thresholdMedium: 10,+};++export function SeverityMatrixBuilder() {+ const [value, setValue] = useState<Values>(defaultValues);++ const severity = classifySeverity(value);+ const reason = classifyReason(value);+ const meta = SEVERITY_META[severity];+ const thresholdsOrdered =+ value.thresholdMedium < value.thresholdHigh &&+ value.thresholdHigh < value.thresholdCritical;++ return (+ <div className="not-prose space-y-8">+ {/* Calculator */}+ <div className="space-y-4">+ {/* Result */}+ <div className={`space-y-3 border-2 p-4 ${SEVERITY_BORDER[severity]}`}>+ <div className="space-y-1">+ <p className="mt-0! font-medium font-mono text-2xl">+ {meta.emoji} {severity} β {meta.label}+ </p>+ <p className="text-muted-foreground text-sm">{reason}</p>+ </div>+ <dl className="grid grid-cols-2 gap-x-4 gap-y-2 text-sm sm:grid-cols-3">+ <div>+ <dt className="text-muted-foreground">Response time</dt>+ <dd className="font-medium text-foreground">+ {meta.responseTime}+ </dd>+ </div>+ <div>+ <dt className="text-muted-foreground">Update cadence</dt>+ <dd className="font-medium text-foreground">+ {meta.updateCadence}+ </dd>+ </div>+ <div>+ <dt className="text-muted-foreground">Postmortem</dt>+ <dd className="font-medium text-foreground">{meta.postmortem}</dd>+ </div>+ <div>+ <dt className="text-muted-foreground">Status page</dt>+ <dd className="font-medium text-foreground">+ {meta.statusPageLabel}+ </dd>+ </div>+ <div>+ <dt className="text-muted-foreground">Escalation</dt>+ <dd className="font-medium text-foreground">{meta.escalation}</dd>+ </div>+ <div>+ <dt className="text-muted-foreground">Communication</dt>+ <dd className="font-medium text-foreground">+ {meta.communication}+ </dd>+ </div>+ </dl>+ </div>++ <div className="space-y-3">+ <div className="flex items-center justify-between">+ <Label className="text-base" htmlFor="users-affected">+ Users affected+ </Label>+ <span className="font-medium font-mono text-base text-foreground">+ {value.usersAffected}%+ </span>+ </div>+ <Slider+ id="users-affected"+ value={[value.usersAffected]}+ onValueChange={(values) =>+ setValue((v) => ({ ...v, usersAffected: values[0] }))+ }+ className="[&_[data-slot=slider-thumb]]:size-5 [&_[data-slot=slider-thumb]]:rounded-none [&_[data-slot=slider-track]]:rounded-none"+ min={0}+ max={100}+ step={5}+ />+ </div>+ <div className="grid gap-4 sm:grid-cols-2">+ <div className="flex items-start space-x-3">+ <Checkbox+ id="security-impact"+ checked={value.securityImpact}+ onCheckedChange={(checked) =>+ setValue((v) => ({ ...v, securityImpact: checked === true }))+ }+ className="size-5 rounded-none [&_svg]:size-4"+ />+ <Label+ htmlFor="security-impact"+ className="flex flex-col items-start gap-0 text-base"+ >+ <span>Security impact</span>+ <span className="text-muted-foreground">+ Confirmed security or data breach+ </span>+ </Label>+ </div>+ <div className="flex items-start space-x-3">+ <Checkbox+ id="sla-breach"+ checked={value.slaBreach}+ onCheckedChange={(checked) =>+ setValue((v) => ({ ...v, slaBreach: checked === true }))+ }+ className="size-5 rounded-none [&_svg]:size-4"+ />+ <Label+ htmlFor="sla-breach"+ className="flex flex-col items-start gap-0 text-base"+ >+ <span>SLA breach</span>+ <span className="text-muted-foreground">+ Active contractual SLA at risk+ </span>+ </Label>+ </div>+ </div>+ </div>++ {/* Test Scenarios */}+ <div className="space-y-2">+ <Label className="text-base">Test scenarios</Label>+ <div className="flex flex-wrap gap-2">+ {TEST_SCENARIOS.map((scenario) => {+ const isActive =+ scenario.usersAffected === value.usersAffected &&+ scenario.securityImpact === value.securityImpact &&+ scenario.slaBreach === value.slaBreach;+ return (+ <Button+ key={scenario.label}+ type="button"+ size="sm"+ variant={isActive ? "default" : "outline"}+ className="rounded-none"+ onClick={() =>+ setValue((v) => ({+ ...v,+ usersAffected: scenario.usersAffected,+ securityImpact: scenario.securityImpact,+ slaBreach: scenario.slaBreach,+ }))+ }+ >+ {scenario.label}+ </Button>+ );+ })}+ </div>+ </div>++ {/* Customize Thresholds */}+ <Details summary="Customize thresholds">+ <div className="grid grid-cols-3 gap-4">+ <div className="space-y-1">+ <Label+ htmlFor="threshold-critical"+ className="text-muted-foreground text-sm"+ >+ SEV0 β₯+ </Label>+ <div className="relative">+ <Input+ id="threshold-critical"+ type="number"+ min={0}+ step={5}+ max={100}+ value={value.thresholdCritical}+ onChange={(e) =>+ setValue((v) => ({+ ...v,+ thresholdCritical: Number(e.target.value),+ }))+ }+ className="h-auto! rounded-none p-4 pr-8 text-base md:text-base"+ />+ <span className="-translate-y-1/2 pointer-events-none absolute top-1/2 right-4 text-muted-foreground">+ %+ </span>+ </div>+ </div>+ <div className="space-y-1">+ <Label+ htmlFor="threshold-high"+ className="text-muted-foreground text-sm"+ >+ SEV1 β₯+ </Label>+ <div className="relative">+ <Input+ id="threshold-high"+ type="number"+ min={0}+ step={5}+ max={100}+ value={value.thresholdHigh}+ onChange={(e) =>+ setValue((v) => ({+ ...v,+ thresholdHigh: Number(e.target.value),+ }))+ }+ className="h-auto! rounded-none p-4 pr-8 text-base md:text-base"+ />+ <span className="-translate-y-1/2 pointer-events-none absolute top-1/2 right-4 text-muted-foreground">+ %+ </span>+ </div>+ </div>+ <div className="space-y-1">+ <Label+ htmlFor="threshold-medium"+ className="text-muted-foreground text-sm"+ >+ SEV2 β₯+ </Label>+ <div className="relative">+ <Input+ id="threshold-medium"+ type="number"+ min={0}+ step={5}+ max={100}+ value={value.thresholdMedium}+ onChange={(e) =>+ setValue((v) => ({+ ...v,+ thresholdMedium: Number(e.target.value),+ }))+ }+ className="h-auto! rounded-none p-4 pr-8 text-base md:text-base"+ />+ <span className="-translate-y-1/2 pointer-events-none absolute top-1/2 right-4 text-muted-foreground">+ %+ </span>+ </div>+ </div>+ </div>+ {!thresholdsOrdered && (+ <p className="text-destructive text-sm">+ Thresholds must be in ascending order: SEV2 < SEV1 < SEV0.+ </p>+ )}+ </Details>+ </div>+ );+}diff --git a/apps/web/src/app/(landing)/play/severity-matrix/page.tsx b/apps/web/src/app/(landing)/play/severity-matrix/page.tsxnew file mode 100644index 000000000..0a4034c65--- /dev/null+++ b/apps/web/src/app/(landing)/play/severity-matrix/page.tsx@@ -0,0 +1,47 @@+import { CustomMDX } from "@/content/mdx";+import { getToolsPage } from "@/content/utils";+import { BASE_URL, getPageMetadata } from "@/lib/metadata/shared-metadata";+import {+ createJsonLDGraph,+ getJsonLDBreadcrumbList,+ getJsonLDFAQPage,+ getJsonLDWebPage,+} from "@/lib/metadata/structured-data";+import type { Metadata } from "next";+import { SeverityMatrixBuilder } from "./client";++export function generateMetadata(): Metadata {+ const page = getToolsPage("severity-matrix");+ return getPageMetadata(page, "play");+}++export default function Page() {+ const page = getToolsPage("severity-matrix");++ const jsonLDGraph = createJsonLDGraph([+ getJsonLDWebPage(page),+ getJsonLDBreadcrumbList([+ { name: "Home", url: BASE_URL },+ { name: "Playground", url: `${BASE_URL}/play` },+ { name: page.metadata.title, url: `${BASE_URL}/play/severity-matrix` },+ ]),+ getJsonLDFAQPage(page),+ ]);++ return (+ <section className="prose dark:prose-invert max-w-none space-y-4">+ <script+ type="application/ld+json"+ suppressHydrationWarning+ // biome-ignore lint/security/noDangerouslySetInnerHtml: <explanation>+ dangerouslySetInnerHTML={{+ __html: JSON.stringify(jsonLDGraph).replace(/</g, "\\u003c"),+ }}+ />+ <h1>{page.metadata.title}</h1>+ <p className="text-lg">{page.metadata.description}</p>+ <SeverityMatrixBuilder />+ <CustomMDX source={page.content} />+ </section>+ );+}diff --git a/apps/web/src/content/mdx-components/button-link.tsx b/apps/web/src/content/mdx-components/button-link.tsxnew file mode 100644index 000000000..75ed1e255--- /dev/null+++ b/apps/web/src/content/mdx-components/button-link.tsx@@ -0,0 +1,19 @@+import { Button } from "@openstatus/ui/components/ui/button";+import type React from "react";+import { CustomLink } from "./custom-link";++export function ButtonLink(+ props: React.ComponentProps<typeof Button> & { href: string },+) {+ return (+ <Button+ variant="outline"+ size="lg"+ className="no-underline! h-auto rounded-none px-4 py-4 text-base"+ asChild+ {...props}+ >+ <CustomLink href={props.href}>{props.children}</CustomLink>+ </Button>+ );+}diff --git a/apps/web/src/content/mdx-components/code.tsx b/apps/web/src/content/mdx-components/code.tsxnew file mode 100644index 000000000..d68e6e0f8--- /dev/null+++ b/apps/web/src/content/mdx-components/code.tsx@@ -0,0 +1,30 @@+import type React from "react";+import { highlight } from "sugar-high";++export function Code({+ children,+ className,+ ...props+}: React.ComponentProps<"code">) {+ // Only apply syntax highlighting if a language is specified (className contains "language-")+ const hasLanguage = className?.includes("language-");++ if (hasLanguage) {+ const codeHTML = highlight(children?.toString() ?? "");+ return (+ <code+ // biome-ignore lint/security/noDangerouslySetInnerHtml: <explanation>+ dangerouslySetInnerHTML={{ __html: codeHTML }}+ className={className}+ {...props}+ />+ );+ }++ // Plain code block without language - render as-is+ return (+ <code className={className} {...props}>+ {children}+ </code>+ );+}diff --git a/apps/web/src/content/mdx-components/custom-image.tsx b/apps/web/src/content/mdx-components/custom-image.tsxnew file mode 100644index 000000000..3d8c87edd--- /dev/null+++ b/apps/web/src/content/mdx-components/custom-image.tsx@@ -0,0 +1,78 @@+import { existsSync } from "node:fs";+import { join } from "node:path";+import { getImageDimensions } from "@/lib/image-dimensions";+import { cn } from "@/lib/utils";+import Image from "next/image";+import { ImageZoom, ZoomableImage } from "../image-zoom";++export function CustomImage({+ className,+ ...props+}: React.ComponentProps<typeof Image>) {+ const { src, alt, width, height, ...rest } = props;++ if (!src || typeof src !== "string") {+ return (+ <figure>+ <ImageZoom+ backdropClassName={cn(+ '[&_[data-rmiz-modal-overlay="visible"]]:bg-background/80',+ )}+ zoomMargin={16}+ >+ <Image+ className={className}+ src={src}+ alt={alt ?? "image"}+ fill+ sizes="100vw"+ style={{ objectFit: "contain" }}+ {...rest}+ />+ </ImageZoom>+ <figcaption>{alt}</figcaption>+ </figure>+ );+ }++ // Get actual image dimensions from filesystem+ const dimensions = getImageDimensions(src);+ const imageWidth = width || dimensions?.width || 1200;+ const imageHeight = height || dimensions?.height || 630;++ // Generate dark mode image path by adding .dark before extension+ const getDarkImagePath = (path: string) => {+ const match = path.match(/^(.+)(\.[^.]+)$/);+ if (match) {+ return `${match[1]}.dark${match[2]}`;+ }+ return path;+ };++ // Check if dark image exists, fallback to light version if not+ const checkDarkImageExists = (darkPath: string) => {+ // If path starts with /, it's in the public directory+ if (darkPath.startsWith("/")) {+ const publicPath = join(process.cwd(), "public", darkPath);+ return existsSync(publicPath);+ }+ // For relative paths, check relative to public+ const publicPath = join(process.cwd(), "public", darkPath);+ return existsSync(publicPath);+ };++ const darkSrc = getDarkImagePath(src);+ const useDarkImage = checkDarkImageExists(darkSrc);++ return (+ <ZoomableImage+ {...rest}+ src={src}+ alt={alt}+ className={className}+ darkSrc={useDarkImage ? darkSrc : undefined}+ imageWidth={imageWidth as number}+ imageHeight={imageHeight as number}+ />+ );+}diff --git a/apps/web/src/content/mdx-components/custom-link.tsx b/apps/web/src/content/mdx-components/custom-link.tsxnew file mode 100644index 000000000..92fa47b50--- /dev/null+++ b/apps/web/src/content/mdx-components/custom-link.tsx@@ -0,0 +1,20 @@+import Link from "next/link";+import type React from "react";++export function CustomLink(props: React.ComponentProps<"a">) {+ const href = props.href ?? "";++ if (href.startsWith("/")) {+ return (+ <Link href={href} {...props}>+ {props.children}+ </Link>+ );+ }++ if (href.startsWith("#")) {+ return <a {...props} />;+ }++ return <a target="_blank" rel="noopener noreferrer" {...props} />;+}diff --git a/apps/web/src/content/mdx-components/details.tsx b/apps/web/src/content/mdx-components/details.tsxnew file mode 100644index 000000000..1bb488fd1--- /dev/null+++ b/apps/web/src/content/mdx-components/details.tsx@@ -0,0 +1,21 @@+import React from "react";++export function Details({+ children,+ summary,+ open = false,+}: {+ children: React.ReactNode;+ summary: string;+ open?: boolean;+}) {+ return (+ <details open={open}>+ <summary>{summary}</summary>+ {React.isValidElement(children)+ ? // biome-ignore lint/suspicious/noExplicitAny: <explanation>+ React.cloneElement(children, { hidden: "until-found" } as any)+ : children}+ </details>+ );+}diff --git a/apps/web/src/content/mdx-components/grid.tsx b/apps/web/src/content/mdx-components/grid.tsxnew file mode 100644index 000000000..8bc439611--- /dev/null+++ b/apps/web/src/content/mdx-components/grid.tsx@@ -0,0 +1,55 @@+import { cn } from "@/lib/utils";+import type React from "react";++export function Grid({+ cols = 2,+ children,+ className,+}: {+ cols?: 1 | 2 | 3 | 4 | 5;+ children: React.ReactNode;+ className?: string;+}) {+ const colsClass = {+ 1: "md:grid-cols-1",+ 2: "md:grid-cols-2",+ 3: "md:grid-cols-3",+ 4: "md:grid-cols-4",+ 5: "md:grid-cols-5",+ };++ // Remove top border from all except first row+ const topBorderClass = {+ 1: "[&>*]:border-t-0 [&>*:first-child]:border-t",+ 2: "[&>*]:border-t-0 [&>*:first-child]:border-t md:[&>*:nth-child(-n+2)]:border-t",+ 3: "[&>*]:border-t-0 [&>*:first-child]:border-t md:[&>*:nth-child(-n+3)]:border-t",+ 4: "[&>*]:border-t-0 [&>*:first-child]:border-t md:[&>*:nth-child(-n+4)]:border-t",+ 5: "[&>*]:border-t-0 [&>*:first-child]:border-t md:[&>*:nth-child(-n+5)]:border-t",+ };++ // Remove left border from all except first column (only on md+ screens)+ const leftBorderClass = {+ 1: "",+ 2: "md:[&>*]:border-l-0 md:[&>*:nth-child(2n+1)]:border-l",+ 3: "md:[&>*]:border-l-0 md:[&>*:nth-child(3n+1)]:border-l",+ 4: "md:[&>*]:border-l-0 md:[&>*:nth-child(4n+1)]:border-l",+ 5: "md:[&>*]:border-l-0 md:[&>*:nth-child(5n+1)]:border-l",+ };++ return (+ <div+ className={cn(+ "my-4 grid grid-cols-1",+ "[&>*]:border [&>*]:border-border [&>*]:p-4",+ // NOTE: remove extra margin from prose grid cells of first and last element+ "[&>*>*:first-child]:!mt-0 [&>*>*:last-child]:!mb-0",+ colsClass[cols],+ topBorderClass[cols],+ leftBorderClass[cols],+ className,+ )}+ >+ {children}+ </div>+ );+}diff --git a/apps/web/src/content/mdx-components/heading.tsx b/apps/web/src/content/mdx-components/heading.tsxnew file mode 100644index 000000000..41d0c7da7--- /dev/null+++ b/apps/web/src/content/mdx-components/heading.tsx@@ -0,0 +1,34 @@+import React from "react";++export function slugify(str: string) {+ return str+ .toString()+ .toLowerCase()+ .trim() // Remove whitespace from both ends of a string+ .replace(/\s+/g, "-") // Replace spaces with -+ .replace(/&/g, "-and-") // Replace & with 'and'+ .replace(/[^\w-]+/g, "") // Remove all non-word characters except for -+ .replace(/--+/g, "-"); // Replace multiple - with single -+}++export function createHeading(level: number) {+ const Heading = ({ children }: { children: React.ReactNode }) => {+ const slug = slugify(children?.toString() ?? "");+ return React.createElement(+ `h${level}`,+ { id: slug },+ [+ React.createElement("a", {+ href: `#${slug}`,+ key: `link-${slug}`,+ className: "anchor",+ }),+ ],+ children,+ );+ };++ Heading.displayName = `Heading${level}`;++ return Heading;+}diff --git a/apps/web/src/content/mdx-components/index.tsx b/apps/web/src/content/mdx-components/index.tsxnew file mode 100644index 000000000..44cf1cf29--- /dev/null+++ b/apps/web/src/content/mdx-components/index.tsx@@ -0,0 +1,35 @@+import { LatencyChartTable } from "../latency-chart-table";+import { ButtonLink } from "./button-link";+import { Code } from "./code";+import { CustomImage } from "./custom-image";+import { CustomLink } from "./custom-link";+import { Details } from "./details";+import { Grid } from "./grid";+import { createHeading } from "./heading";+import { Pre } from "./pre";+import { MDXStatusPageExample } from "./status-page-example";+import { Table } from "./table";+import { MDXTweet } from "./tweet";++export { slugify } from "./heading";++export const components = {+ h1: createHeading(1),+ h2: createHeading(2),+ h3: createHeading(3),+ h4: createHeading(4),+ h5: createHeading(5),+ h6: createHeading(6),+ Image: CustomImage,+ a: CustomLink,+ ButtonLink: ButtonLink,+ code: Code,+ pre: Pre,+ table: Table,+ Grid,+ Details, // Capital D for JSX usage with props+ details: Details, // lowercase for HTML tag replacement+ SimpleChart: LatencyChartTable,+ Tweet: MDXTweet,+ StatusPageExample: MDXStatusPageExample,+};diff --git a/apps/web/src/content/mdx-components/pre.tsx b/apps/web/src/content/mdx-components/pre.tsxnew file mode 100644index 000000000..97ce3dd25--- /dev/null+++ b/apps/web/src/content/mdx-components/pre.tsx@@ -0,0 +1,34 @@+import React from "react";+import { CopyButton } from "../copy-button";++function extractTextFromReactNode(node: React.ReactNode): string {+ if (typeof node === "string") {+ return node;+ }+ if (typeof node === "number") {+ return String(node);+ }+ if (Array.isArray(node)) {+ return node.map(extractTextFromReactNode).join("");+ }+ if (React.isValidElement(node)) {+ const props = node.props as { children?: React.ReactNode };+ if (props.children) {+ return extractTextFromReactNode(props.children);+ }+ }+ return "";+}++export function Pre({ children, ...props }: React.ComponentProps<"pre">) {+ const textContent = extractTextFromReactNode(children);+ return (+ <div className="relative">+ <pre {...props}>{children}</pre>+ <CopyButton+ copyText={textContent}+ className="absolute top-px right-px backdrop-blur-xs"+ />+ </div>+ );+}diff --git a/apps/web/src/content/mdx-components/status-page-example.tsx b/apps/web/src/content/mdx-components/status-page-example.tsxnew file mode 100644index 000000000..9da9e5262--- /dev/null+++ b/apps/web/src/content/mdx-components/status-page-example.tsx@@ -0,0 +1,10 @@+import { ComponentHighlighter } from "../component-highlighter";+import { StatusPageExample } from "../shadcn-registry-example";++export function MDXStatusPageExample() {+ return (+ <ComponentHighlighter>+ <StatusPageExample />+ </ComponentHighlighter>+ );+}diff --git a/apps/web/src/content/mdx-components/table.tsx b/apps/web/src/content/mdx-components/table.tsxnew file mode 100644index 000000000..0909ea0d8--- /dev/null+++ b/apps/web/src/content/mdx-components/table.tsx@@ -0,0 +1,9 @@+import type React from "react";++export function Table(props: React.ComponentProps<"table">) {+ return (+ <div className="table-wrapper">+ <table {...props} />+ </div>+ );+}diff --git a/apps/web/src/content/mdx-components/tweet.tsx b/apps/web/src/content/mdx-components/tweet.tsxnew file mode 100644index 000000000..22225e460--- /dev/null+++ b/apps/web/src/content/mdx-components/tweet.tsx@@ -0,0 +1,9 @@+import { Tweet, type TweetProps } from "react-tweet";++export function MDXTweet(props: TweetProps) {+ return (+ <div data-theme="light" className="not-prose [&>div]:mx-auto">+ <Tweet {...props} />+ </div>+ );+}diff --git a/apps/web/src/content/mdx.tsx b/apps/web/src/content/mdx.tsxindex 8b1157aed..b6050cfee 100644--- a/apps/web/src/content/mdx.tsx+++ b/apps/web/src/content/mdx.tsx@@ -1,328 +1,10 @@-import { existsSync } from "node:fs";-import { join } from "node:path";-import { getImageDimensions } from "@/lib/image-dimensions";-import { cn } from "@/lib/utils";-import { Button } from "@openstatus/ui/components/ui/button";import { MDXRemote, type MDXRemoteProps } from "next-mdx-remote/rsc";-import Image from "next/image";-import Link from "next/link";import React from "react";-import { Tweet, type TweetProps } from "react-tweet";import remarkGfm from "remark-gfm";-import { highlight } from "sugar-high";-import { ComponentHighlighter } from "./component-highlighter";-import { CopyButton } from "./copy-button";import { HighlightText } from "./highlight-text";-import { ImageZoom, ZoomableImage } from "./image-zoom";-import { LatencyChartTable } from "./latency-chart-table";-import { StatusPageExample } from "./shadcn-registry-example";+import { components } from "./mdx-components";-function Table(props: React.ComponentProps<"table">) {- return (- <div className="table-wrapper">- <table {...props} />- </div>- );-}--function Grid({- cols = 2,- children,- className,-}: {- cols?: 1 | 2 | 3 | 4 | 5;- children: React.ReactNode;- className?: string;-}) {- const colsClass = {- 1: "md:grid-cols-1",- 2: "md:grid-cols-2",- 3: "md:grid-cols-3",- 4: "md:grid-cols-4",- 5: "md:grid-cols-5",- };-- // Remove top border from all except first row- const topBorderClass = {- 1: "[&>*]:border-t-0 [&>*:first-child]:border-t",- 2: "[&>*]:border-t-0 [&>*:first-child]:border-t md:[&>*:nth-child(-n+2)]:border-t",- 3: "[&>*]:border-t-0 [&>*:first-child]:border-t md:[&>*:nth-child(-n+3)]:border-t",- 4: "[&>*]:border-t-0 [&>*:first-child]:border-t md:[&>*:nth-child(-n+4)]:border-t",- 5: "[&>*]:border-t-0 [&>*:first-child]:border-t md:[&>*:nth-child(-n+5)]:border-t",- };-- // Remove left border from all except first column (only on md+ screens)- const leftBorderClass = {- 1: "",- 2: "md:[&>*]:border-l-0 md:[&>*:nth-child(2n+1)]:border-l",- 3: "md:[&>*]:border-l-0 md:[&>*:nth-child(3n+1)]:border-l",- 4: "md:[&>*]:border-l-0 md:[&>*:nth-child(4n+1)]:border-l",- 5: "md:[&>*]:border-l-0 md:[&>*:nth-child(5n+1)]:border-l",- };-- return (- <div- className={cn(- "my-4 grid grid-cols-1",- "[&>*]:border [&>*]:border-border [&>*]:p-4",- // NOTE: remove extra margin from prose grid cells of first and last element- "[&>*>*:first-child]:!mt-0 [&>*>*:last-child]:!mb-0",- colsClass[cols],- topBorderClass[cols],- leftBorderClass[cols],- className,- )}- >- {children}- </div>- );-}--function CustomLink(props: React.ComponentProps<"a">) {- const href = props.href ?? "";-- if (href.startsWith("/")) {- return (- <Link href={href} {...props}>- {props.children}- </Link>- );- }-- if (href.startsWith("#")) {- return <a {...props} />;- }-- return <a target="_blank" rel="noopener noreferrer" {...props} />;-}--function ButtonLink(- props: React.ComponentProps<typeof Button> & { href: string },-) {- return (- <Button- variant="outline"- size="lg"- className="no-underline! h-auto rounded-none px-4 py-4 text-base"- asChild- {...props}- >- <CustomLink href={props.href}>{props.children}</CustomLink>- </Button>- );-}--function Code({ children, className, ...props }: React.ComponentProps<"code">) {- // Only apply syntax highlighting if a language is specified (className contains "language-")- const hasLanguage = className?.includes("language-");-- if (hasLanguage) {- const codeHTML = highlight(children?.toString() ?? "");- return (- <code- // biome-ignore lint/security/noDangerouslySetInnerHtml: <explanation>- dangerouslySetInnerHTML={{ __html: codeHTML }}- className={className}- {...props}- />- );- }-- // Plain code block without language - render as-is- return (- <code className={className} {...props}>- {children}- </code>- );-}--function extractTextFromReactNode(node: React.ReactNode): string {- if (typeof node === "string") {- return node;- }- if (typeof node === "number") {- return String(node);- }- if (Array.isArray(node)) {- return node.map(extractTextFromReactNode).join("");- }- if (React.isValidElement(node)) {- const props = node.props as { children?: React.ReactNode };- if (props.children) {- return extractTextFromReactNode(props.children);- }- }- return "";-}--function Pre({ children, ...props }: React.ComponentProps<"pre">) {- const textContent = extractTextFromReactNode(children);- return (- <div className="relative">- <pre {...props}>{children}</pre>- <CopyButton- copyText={textContent}- className="absolute top-px right-px backdrop-blur-xs"- />- </div>- );-}--export function slugify(str: string) {- return str- .toString()- .toLowerCase()- .trim() // Remove whitespace from both ends of a string- .replace(/\s+/g, "-") // Replace spaces with -- .replace(/&/g, "-and-") // Replace & with 'and'- .replace(/[^\w-]+/g, "") // Remove all non-word characters except for -- .replace(/--+/g, "-"); // Replace multiple - with single --}--function createHeading(level: number) {- const Heading = ({ children }: { children: React.ReactNode }) => {- const slug = slugify(children?.toString() ?? "");- return React.createElement(- `h${level}`,- { id: slug },- [- React.createElement("a", {- href: `#${slug}`,- key: `link-${slug}`,- className: "anchor",- }),- ],- children,- );- };-- Heading.displayName = `Heading${level}`;-- return Heading;-}--function Details({- children,- summary,- open = false,-}: {- children: React.ReactNode;- summary: string;- open?: boolean;-}) {- return (- <details open={open}>- <summary>{summary}</summary>- {React.isValidElement(children)- ? // biome-ignore lint/suspicious/noExplicitAny: <explanation>- React.cloneElement(children, { hidden: "until-found" } as any)- : children}- </details>- );-}--function CustomImage({- className,- ...props-}: React.ComponentProps<typeof Image>) {- const { src, alt, width, height, ...rest } = props;-- if (!src || typeof src !== "string") {- return (- <figure>- <ImageZoom- backdropClassName={cn(- '[&_[data-rmiz-modal-overlay="visible"]]:bg-background/80',- )}- zoomMargin={16}- >- <Image- className={className}- src={src}- alt={alt ?? "image"}- fill- sizes="100vw"- style={{ objectFit: "contain" }}- {...rest}- />- </ImageZoom>- <figcaption>{alt}</figcaption>- </figure>- );- }-- // Get actual image dimensions from filesystem- const dimensions = getImageDimensions(src);- const imageWidth = width || dimensions?.width || 1200;- const imageHeight = height || dimensions?.height || 630;-- // Generate dark mode image path by adding .dark before extension- const getDarkImagePath = (path: string) => {- const match = path.match(/^(.+)(\.[^.]+)$/);- if (match) {- return `${match[1]}.dark${match[2]}`;- }- return path;- };-- // Check if dark image exists, fallback to light version if not- const checkDarkImageExists = (darkPath: string) => {- // If path starts with /, it's in the public directory- if (darkPath.startsWith("/")) {- const publicPath = join(process.cwd(), "public", darkPath);- return existsSync(publicPath);- }- // For relative paths, check relative to public- const publicPath = join(process.cwd(), "public", darkPath);- return existsSync(publicPath);- };-- const darkSrc = getDarkImagePath(src);- const useDarkImage = checkDarkImageExists(darkSrc);-- return (- <ZoomableImage- {...rest}- src={src}- alt={alt}- className={className}- darkSrc={useDarkImage ? darkSrc : undefined}- imageWidth={imageWidth as number}- imageHeight={imageHeight as number}- />- );-}--export const components = {- h1: createHeading(1),- h2: createHeading(2),- h3: createHeading(3),- h4: createHeading(4),- h5: createHeading(5),- h6: createHeading(6),- Image: CustomImage,- a: CustomLink,- ButtonLink: ButtonLink,- code: Code,- pre: Pre,- table: Table,- Grid,- Details, // Capital D for JSX usage with props- details: Details, // lowercase for HTML tag replacement- SimpleChart: LatencyChartTable,- Tweet: (props: TweetProps) => {- return (- <div data-theme="light" className="not-prose [&>div]:mx-auto">- <Tweet {...props} />- </div>- );- },- StatusPageExample: () => (- <ComponentHighlighter>- <StatusPageExample />- </ComponentHighlighter>- ),-};+export { components, slugify } from "./mdx-components";function MDXContent(props: MDXRemoteProps) {return (diff --git a/apps/web/src/content/pages/guides/incident-severity-matrix.mdx b/apps/web/src/content/pages/guides/incident-severity-matrix.mdxnew file mode 100644index 000000000..b1f356d6a--- /dev/null+++ b/apps/web/src/content/pages/guides/incident-severity-matrix.mdx@@ -0,0 +1,312 @@+---+title: "Incident Severity Matrix Template"+description: "Ready-to-use templates for classifying and communicating incidents by severity level. Covers status page message templates, postmortem requirements, and real-world examples for SEV0 through SEV3."+author: "openstatus"+publishedAt: "2026-02-26"+category: "template"+howto:+ totalTime: "PT30M"+ steps:+ - name: "Define your severity thresholds"+ text: "Set measurable thresholds for each severity level based on percentage of users affected. Use the interactive builder to customize thresholds to your team's operational reality."+ - name: "Classify the incident"+ text: "Apply the classification rules in order: security impact always triggers SEV0, then check user percentage against thresholds, then apply the SLA modifier if active."+ url: "#severity-matrix"+ - name: "Post to your status page"+ text: "Use the per-severity message templates to post a consistent public update. Commit to the update cadence for your severity level and never go more than one hour without an update on any active SEV0 or SEV1."+ url: "#status-page-message-templates"+ - name: "Escalate and run the postmortem"+ text: "Follow the escalation path for the classified severity level. SEV0 and SEV1 always require a postmortem. Close the loop by publishing findings and action items."+ url: "#postmortem-requirements"+faq:+ - question: "What does SEV0 mean?"+ answer: "SEV0 indicates a critical incident β typically a complete service outage or confirmed security breach that requires immediate response from senior engineering leadership. It's the highest severity level and triggers the most aggressive communication and escalation protocols."+ - question: "How many severity levels should we use?"+ answer: "Most teams use 3 or 4 levels. Four levels (SEV0 through SEV3) provide enough granularity to distinguish between a full outage and a minor cosmetic bug without overcomplicating triage during a live incident."+ - question: "What is the difference between severity and priority?"+ answer: "Severity measures the impact of an incident β how many users are affected and how badly. Priority reflects business urgency and resource allocation. A typo on your pricing page might be low severity but high priority if it's costing you conversions. Your severity matrix should classify based on impact alone; priority is a triage decision."+ - question: "Should security incidents always be SEV0?"+ answer: "In most cases, yes. Security incidents carry outsized risk even when few users are immediately affected β the blast radius can expand quickly and the reputational impact is disproportionate. Treating all confirmed security incidents as SEV0 ensures you mobilize the right resources immediately."+ - question: "How often should we review our severity matrix?"+ answer: "Review it quarterly, or after any major incident where the classification felt wrong. If your team consistently debates whether something is a SEV1 or SEV2, your thresholds probably need adjustment."+ - question: "When is a postmortem required?"+ answer: "SEV0 and SEV1 incidents always require a postmortem. SEV2 requires a team-level postmortem. SEV3 postmortems are optional. The postmortem closes the loop by documenting root cause, timeline, and action items to prevent recurrence."+---++Use these templates when classifying and communicating production incidents. Based on real-world patterns from GitHub, Stripe, and Vercel status pages. Use the [interactive builder](/play/severity-matrix) to classify incidents and customize thresholds for your team.++## When to Use This Guide++- An incident has just been detected and you need to classify it fast+- You're writing a status page update and want consistent, professional language+- You're setting up your team's incident response process for the first time+- A postmortem revealed your classification or communication was inconsistent++## Severity Matrix++Copy these tables into your runbook, wiki, or Notion page.++Each row maps a severity level to its user impact threshold, required response time, and communication protocol. Classification should be deterministic β given the same inputs, every engineer on your team should reach the same row.++```markdown+| Severity | Users Affected | Security | Response Time | Status Page Label | Communication | Postmortem |+|----------|---------------|----------|---------------|-------------------|---------------|------------|+| π΄ SEV0 β Critical | β₯80% OR security incident | Yes | 15 minutes | Major Outage | Immediate public update + all-hands | Required |+| π SEV1 β High | β₯50% | No | 30 minutes | Partial Outage | Public update within 15 min | Required |+| π‘ SEV2 β Medium | β₯10% | No | 2 hours | Degraded Performance | Status page update + ticket | Required (team) |+| π’ SEV3 β Low | <10% | No | 1 business day | Minor Issue | Internal ticket only | Optional |+```++Once the severity is set, this table tells every engineer exactly who owns it and when to escalate. If an incident isn't resolved within the auto-escalate window, re-classify upward immediately β don't wait.++```markdown+| Severity | First Response | Update Cadence | Escalation Path | Auto-Escalate If |+|----------|---------------|----------------|-----------------|-----------------|+| SEV0 | 15 min | Every 15 min | VP Engineering + on-call | β |+| SEV1 | 30 min | Every 30 min | Engineering lead | Not resolved in 2h β SEV0 review |+| SEV2 | 2 hours | Every 2 hours | Team lead | Not resolved in 4h β SEV1 |+| SEV3 | 1 business day | Daily | Assigned engineer | Spreads to more systems β re-classify |+```++## Status Page Message Templates++Never go more than one hour without a public update on any active SEV0 or SEV1. Even if there's no new information, a "we're still investigating" update is better than silence.++### SEV0 β Critical++**Investigating**++```+We are investigating a critical incident affecting [description of impact]. Our on-call team has been paged and we are actively working to identify the root cause. Next update in 15 minutes.+```++**Identified**++```+We have identified the root cause as [brief description]. A fix is being deployed. We will continue to provide updates every 15 minutes until service is fully restored.+```++**Monitoring**++```+A fix has been deployed. We are monitoring for full recovery and are seeing signs of improvement. Next update in 15 minutes.+```++**Resolved**++```+This incident has been resolved. All systems are operating normally. We apologize for the disruption. A postmortem will be published within 48 hours.+```++---++### SEV1 β High++**Investigating**++```+We are investigating degraded performance affecting [description of impact]. Our team is actively working on this. Next update in 30 minutes.+```++**Identified**++```+We have identified the cause of the degradation. A fix is in progress. Next update in 30 minutes.+```++**Monitoring**++```+A fix has been deployed and we are monitoring for full recovery. Next update in 30 minutes.+```++**Resolved**++```+Service has been fully restored. We apologize for the disruption. Our engineering team will publish a postmortem with root cause and action items.+```++---++### SEV2 β Medium++**Investigating**++```+We are investigating reports of degraded performance affecting a subset of users. Core functionality remains available. We will provide an update within 2 hours.+```++**Identified**++```+We have identified the root cause. A fix is being prepared and we expect resolution within [timeframe].+```++**Monitoring**++```+A fix has been deployed. We are monitoring for full resolution.+```++**Resolved**++```+This issue has been resolved. All systems are operating normally.+```++---++### SEV3 β Low++SEV3 incidents typically do not require a public status page update. If you choose to communicate externally, use these templates.++**Investigating**++```+We are aware of a minor issue affecting a small number of users. Core functionality is not impacted. No immediate action is required on your end.+```++**Identified**++```+We have identified the cause. A fix will be deployed in the normal course of work.+```++**Monitoring**++```+A fix has been deployed and we are monitoring for full resolution.+```++**Resolved**++```+This minor issue has been resolved.+```++## Postmortem Requirements++Closing the incident loop with a postmortem prevents recurrence and builds team knowledge.++| Severity | Postmortem | Who attends | Timeline |+|----------|-----------|-------------|---------|+| SEV0 | Required | Full engineering leadership | Within 48 hours |+| SEV1 | Required | Engineering leads + on-call | Within 72 hours |+| SEV2 | Required (team) | Relevant engineering team | Within 1 week |+| SEV3 | Optional | Assigned engineer | As needed |++When you post the "Resolved" update for a SEV0 or SEV1, commit to the postmortem publicly: "A postmortem will be published at [link] within 48 hours." This sets expectations and holds the team accountable.++## Severity vs Priority++Severity and priority are often conflated, and that conflict tends to surface during live incidents at exactly the wrong time.++**Severity** is objective β it measures blast radius: how many users are affected and how badly. It does not change based on who's asking.++**Priority** is contextual β it reflects how urgently the team should act given business context. The same severity level can warrant different priorities.++Priority levels run P0 (drop everything) through P3 (low urgency), independent of severity:++| Scenario | Severity | Priority | Why |+|----------|----------|----------|-----|+| API down for 90% of users | SEV0 | P0 | Total outage + business impact |+| Button misaligned on pricing page | SEV3 | P1 | Low impact but costs conversions |+| Slow dashboard for 5% of users | SEV2 | P2 | Limited impact, no SLA risk |+| Auth bug during enterprise demo | SEV2 | P0 | Low blast radius, high business risk |++Classify severity based on impact. Decide priority separately during triage. A higher severity level also grants broader authority to take riskier recovery actions β a SEV0 may justify taking a service down entirely to restore stability.++## Roles During a Severity Incident++Assign an **Incident Commander** at the start of every SEV0 or SEV1. One person owns:++- The current severity classification+- All public status page updates+- The escalation decision++This prevents contradictory messages on your status page. If two engineers post updates independently, users see conflicting information at the worst possible time. The IC is the single source of truth for external communication until the incident is resolved.++For SEV2 and below, the assigned engineer handles communication directly without a dedicated IC.++## Real-World Examples++### Database cluster failover++**Scenario**: Primary database fails over to replica. 60% of users experience 2 minutes of downtime. No data loss.+**Classification**: π SEV1 β High (60% users affected)++Full communication arc:++**Investigating**+```+We are investigating degraded performance affecting the majority of users. Our team is actively working to restore service. Next update in 30 minutes.+```++**Identified**+```+We have identified the cause as a database failover. Service is being restored and we are monitoring recovery. Next update in 30 minutes.+```++**Monitoring**+```+The failover has completed and service is recovering. We are monitoring to confirm full stability. Next update in 30 minutes.+```++**Resolved**+```+Service has been fully restored. We apologize for the disruption. Our engineering team will publish a postmortem with root cause and action items.+```++---++### API authentication breach++**Scenario**: Unauthorized access detected on API keys. Only 5% of users affected, but security is compromised.+**Classification**: π΄ SEV0 β Critical (security override)++```+We are investigating a security incident affecting API authentication. Impacted API keys have been revoked as a precaution. Our security team is actively investigating. Next update in 15 minutes.+```++---++### CDN edge node degradation++**Scenario**: One CDN region serving stale assets. 15% of users see outdated content. Workaround: hard refresh.+**Classification**: π‘ SEV2 β Medium (15% users affected)++```+We are investigating reports of stale content being served to users in [region]. A workaround is available: clear your browser cache or perform a hard refresh. We will provide an update within 2 hours.+```++---++### Payment processor timeout++**Scenario**: Stripe webhook failures causing 90% checkout failures. SLA breach triggered.+**Classification**: π΄ SEV0 β Critical (90% users affected)++```+We are investigating a critical issue affecting checkout. The majority of payment attempts are currently failing. Our team is working urgently with our payment provider to restore service. Next update in 15 minutes.+```++---++### CSS regression on settings page++**Scenario**: Button misaligned on settings page. 3% of users affected. Functional workaround exists.+**Classification**: π’ SEV3 β Low (3% users affected)+**Status page message**: No public update needed. Internal ticket created and assigned.++## Tips for Using the Severity Matrix++1. **During a live incident, err high.** Over-escalating one incident costs less than under-escalating and letting user impact compound. Calibrate downward in the postmortem if you overshot.+2. **Watch for severity inflation.** If your team regularly classifies 30%+ of incidents as SEV1, you've lost the signal. Measurable thresholds prevent this from drifting over time.+3. **Auto-escalate on duration.** If a SEV2 is not resolved within 4 hours, trigger a SEV1 review. Unresolved incidents spreading to new systems always warrant re-classification.+4. **Use UTC in all public updates.** For distributed teams and global users, UTC timestamps remove timezone ambiguity and prevent confusion during long-running incidents.+5. **Pin the matrix where it will be found.** In your incident Slack channel, your runbook, and your on-call documentation. A severity matrix only works if engineers can find it in the first 30 seconds of an incident.+6. **Review thresholds quarterly.** Or after any incident where the classification was debated. If your team is consistently arguing about SEV1 vs SEV2, adjust the threshold.++---++Use the [Incident Severity Matrix Builder](/play/severity-matrix) to classify incidents interactively, test your thresholds against real scenarios, and customize the matrix for your team.diff --git a/apps/web/src/content/pages/tools/severity-matrix.mdx b/apps/web/src/content/pages/tools/severity-matrix.mdxnew file mode 100644index 000000000..27859074b--- /dev/null+++ b/apps/web/src/content/pages/tools/severity-matrix.mdx@@ -0,0 +1,80 @@+---+title: "Incident Severity Matrix Builder"+publishedAt: "2026-02-26"+author: "Maximilian Kaske"+description: "Classify incidents with deterministic, auditable rules. Customize thresholds, test scenarios, and export a ready-to-use template for your runbook."+category: "Product"+faq:+ - question: "What does SEV0 mean?"+ answer: "SEV0 indicates a critical incident β typically a complete service outage or confirmed security breach that requires immediate response from senior engineering leadership. It's the highest severity level and triggers the most aggressive communication and escalation protocols."+ - question: "How many severity levels should we use?"+ answer: "Most teams use 3 or 4 levels. Four levels (SEV0 through SEV3) provide enough granularity to distinguish between a full outage and a minor cosmetic bug without overcomplicating triage during a live incident. If you're a small team, 3 levels can work fine β you can always add granularity later."+ - question: "What is the difference between severity and priority?"+ answer: "Severity measures the impact of an incident β how many users are affected and how badly. Priority reflects business urgency and resource allocation. A typo on your pricing page might be low severity but high priority if it's costing you conversions. Your severity matrix should classify based on impact alone; priority is a triage decision."+ - question: "Should security incidents always be SEV0?"+ answer: "In most cases, yes. Security incidents carry outsized risk even when few users are immediately affected β the blast radius can expand quickly and the reputational impact is disproportionate. Treating all confirmed security incidents as SEV0 ensures you mobilize the right resources immediately."+ - question: "How often should we review our severity matrix?"+ answer: "Review it quarterly, or after any major incident where the classification felt wrong. If your team consistently debates whether something is a SEV1 or SEV2, your thresholds probably need adjustment. The builder lets you customize thresholds so your matrix reflects your team's actual operational patterns."+ - question: "Is a severity matrix required for SOC 2?"+ answer: "Not by name, but functionally yes. SOC 2 criterion CC7.4 explicitly requires understanding the 'nature and severity' of an incident to determine the appropriate response time frame. Auditors doing a Type II audit will sample real incidents and check whether your severity classification was applied consistently. Without a documented matrix, that evidence trail doesn't exist. ISO 27001 Annex A 5.25 is even more explicit β it directly mandates categorisation and prioritisation of security events."+ - question: "How does this relate to SLA compliance?"+ answer: "Your severity levels determine how quickly you respond to incidents, which directly affects your cumulative downtime. If your SLA promises 99.9% uptime, you have roughly 8 hours and 46 minutes of allowed downtime per year. A single misclassified SEV0 treated as SEV2 could burn through that budget."+---++## Severity Matrix Template++Copy these tables into your runbook, wiki, or Notion page.++```markdown+| Severity | Users Affected | Security | Response Time | Status Page Label | Communication | Postmortem |+|----------|---------------|----------|---------------|-------------------|---------------|------------|+| π΄ SEV0 β Critical | β₯80% OR security incident | Yes | 15 minutes | Major Outage | Immediate public update + all-hands | Required |+| π SEV1 β High | β₯50% | No | 30 minutes | Partial Outage | Public update within 15 min | Required |+| π‘ SEV2 β Medium | β₯10% | No | 2 hours | Degraded Performance | Status page update + ticket | Required (team) |+| π’ SEV3 β Low | <10% | No | 1 business day | Minor Issue | Internal ticket only | Optional |+```++Once you have your severity levels defined, pair them with explicit response expectations. This table tells every engineer exactly how fast to act and when to escalate β no guessing during an active incident.++### Response Expectations Template++```markdown+| Severity | First Response | Update Cadence | Escalation Path | Auto-Escalate If |+|----------|---------------|----------------|-----------------|-----------------|+| SEV0 | 15 min | Every 15 min | VP Engineering + on-call | β |+| SEV1 | 30 min | Every 30 min | Engineering lead | Not resolved in 2h β SEV0 review |+| SEV2 | 2 hours | Every 2 hours | Team lead | Not resolved in 4h β SEV1 |+| SEV3 | 1 business day | Daily | Assigned engineer | Spreads to more systems β re-classify |+```++## What Is an Incident Severity Matrix?++An incident severity matrix is a structured framework that classifies production incidents based on measurable impact: how many users are affected, whether security is compromised, and whether SLA commitments are at risk.++Without one, incident classification becomes subjective. Different engineers escalate differently. Status page updates are inconsistent. Response times vary depending on who's on call.++A well-defined severity matrix solves this by making classification deterministic. Given the same inputs, every engineer arrives at the same severity level, the same response time expectation, and the same communication protocol.++### Is it required for compliance?++Largely, yes. SOC 2's CC7.4 criterion explicitly states that an organization must obtain "an understanding of the nature and **severity** of the security incident" to determine "the appropriate containment strategy, including a determination of the appropriate response time frame." Without a documented severity framework, you cannot demonstrate consistent, auditable compliance during a Type II audit β where auditors sample real incidents and verify the classification was applied.++ISO 27001 goes further. Annex A control 5.25 directly mandates "effective categorisation and prioritisation of information security events" using impact, urgency, and priority as criteria. It is one of the most explicit requirements across any compliance framework for building exactly this kind of matrix.++NIST SP 800-61, PCI DSS 12.10, and HIPAA's breach determination process all lean on the same concept: you cannot respond proportionally to something you haven't classified.++## SEV0 vs SEV1 vs SEV2 vs SEV3++**SEV0 β Critical**+Complete outage or security breach. No workaround available. Requires immediate response from senior engineering leadership. Public status page should show "Major Outage" and updates should go out every 15 minutes. A postmortem is always required.++**SEV1 β High**+Major degradation affecting most users. Significant business or revenue impact. Requires urgent response from engineering leads. Status page shows "Partial Outage" with 30-minute update cadence. A postmortem is required.++**SEV2 β Medium**+Partial degradation with limited user impact. Standard incident process applies. Status page shows "Degraded Performance" and updates go out every 2 hours. A team-level postmortem is required.++**SEV3 β Low**+Minor bug or cosmetic issue affecting a small percentage of users. Non-urgent resolution on a 1 business day timeline. Typically no public status page update is needed. Postmortem is optional.++See the [Incident Severity Matrix Template](/guides/incident-severity-matrix) for per-severity status page message templates, postmortem requirements, real-world examples, and tips.diff --git a/apps/web/src/data/content.ts b/apps/web/src/data/content.tsindex 99ef720a7..38a90f2f5 100644--- a/apps/web/src/data/content.ts+++ b/apps/web/src/data/content.ts@@ -119,7 +119,9 @@ const toolsSection = {label: "Tools",items: [...getToolsPages()- .filter((page) => page.slug !== "checker-slug")+ .filter(+ (page) => !["checker-slug", "severity-matrix"].includes(page.slug),+ ).map((page) => ({label: page.metadata.title,href: `/play/${page.slug}`,