Skip to content

Commit c92e76b

Browse files
stefanjudisstefanjudis
authored
Merge pull request #162 from checkly/add-ux-status-pages-guide
Add status page guide and IncidentTrigger construct documentation
2 parents a51896c + 5696807 commit c92e76b

11 files changed

+368
-49
lines changed

‎communicate/status-pages/overview.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@ The number of services and subscribers you can have varies by plan. [View pricin
2222

2323
When naming a service, use a name that is identifiable for your users, as this is used when sending out incident notifications.
2424

25+
<Tip>Learn more about contextual services in [Communicate User Feature Availability with Status Pages](/guides/communicate-availability).</Tip>
26+
2527
A service can be used by multiple status pages. When an incident is opened for a service, it will appear on all pages that use it. Subscribers of each of those pages will receive email notifications for the incident.
2628

2729
![Diagram showing the incident flow for manual incidents](/images/docs/images/status-pages/status-pages-manual-incident.jpg)

‎constructs/incident-trigger.mdx‎

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
title: 'IncidentTrigger Configuration'
3+
description: 'Learn how to configure status page incident automation with the Checkly CLI.'
4+
sidebarTitle: 'Incident Trigger'
5+
---
6+
7+
<Tip>
8+
Learn more about Status Pages in [the Status Pages overview](/communicate/status-pages/overview).
9+
</Tip>
10+
11+
Use incident triggers to automatically create and resolve an incident and notify subscribers based on the alert configuration of a monitor or check. This allows you to link synthetic monitoring failures directly to incidents on your status pages.
12+
13+
<CodeGroup>
14+
```ts Basic Example highlight={12-19,28}
15+
import {
16+
Frequency,
17+
IncidentTrigger,
18+
PlaywrightCheck,
19+
StatusPageService,
20+
} from "checkly/constructs";
21+
22+
const searchService = new StatusPageService("search-service", {
23+
name: "Search Service",
24+
});
25+
26+
const searchIncidentTrigger: IncidentTrigger = {
27+
service: searchService,
28+
severity: "MINOR",
29+
name: "Search is down",
30+
description:
31+
"Some users experience issues with the product search. We're investigating.",
32+
notifySubscribers: true,
33+
};
34+
35+
new PlaywrightCheck("playwright-check-suite", {
36+
name: "Search Monitoring",
37+
playwrightConfigPath: "../playwright.config.ts",
38+
activated: true,
39+
pwProjects: ["Search Monitoring"],
40+
locations: ["us-east-1", "eu-west-1", "ap-southeast-2"],
41+
frequency: Frequency.EVERY_10M,
42+
triggerIncident: searchIncidentTrigger,
43+
});
44+
```
45+
</CodeGroup>
46+
47+
## Configuration
48+
49+
<Tabs>
50+
<Tab title="Incident Trigger">
51+
52+
| Parameter | Type | Required | Default | Description |
53+
|-----------|------|----------|---------|-------------|
54+
| `service` | `StatusPageService` | ✅ | - | The status page service that this incident will be associated with |
55+
| `severity` | `IncidentSeverity` | ✅ | - | The severity level of the incident. (`MINOR`, `MEDIUM`, `MAJOR`, `CRITICAL`) |
56+
| `name` | `string` | ✅ | - | The name of the incident. |
57+
| `description` | `string` | ✅ | - | A detailed description of the incident. |
58+
| `notifySubscribers` | `boolean` | ✅ | - | Whether to notify subscribers when the incident is triggered |
59+
60+
</Tab>
61+
</Tabs>
62+
63+
## `IncidentTrigger` Options
64+
65+
<ResponseField name="service" type="StatusPageService" required>
66+
The status page service that this incident will be associated with. When a check or monitor fails, an incident is created for this service and connected status pages.
67+
68+
**Usage:**
69+
70+
```ts highlight={6}
71+
const searchService = new StatusPageService("search-service", {
72+
name: "Search Service",
73+
})
74+
75+
const incidentTrigger: IncidentTrigger = {
76+
service: searchService,
77+
/* More options... */
78+
}
79+
```
80+
81+
**Use cases**: Linking monitors to specific services, automatic incident creation, service-based status tracking.
82+
</ResponseField>
83+
84+
<ResponseField name="severity" type="IncidentSeverity" required>
85+
The severity level of the incident. Determines how the incident is displayed and prioritized.
86+
87+
**Options:**
88+
- `MINOR` - Minor impact, most users unaffected
89+
- `MEDIUM` - Moderate impact, some users affected
90+
- `MAJOR` - Major impact, many users affected
91+
- `CRITICAL` - Critical impact, all users affected
92+
93+
**Usage:**
94+
95+
```ts highlight={3}
96+
const incidentTrigger: IncidentTrigger = {
97+
service: searchService,
98+
severity: "MAJOR",
99+
/* More options... */
100+
}
101+
```
102+
103+
**Use cases**: Incident prioritization, user communication, escalation workflows.
104+
</ResponseField>
105+
106+
<ResponseField name="name" type="string" required>
107+
The name of the incident displayed on the status page. Should clearly communicate the issue to users.
108+
109+
**Usage:**
110+
111+
```ts highlight={3}
112+
const incidentTrigger: IncidentTrigger = {
113+
service: searchService,
114+
name: "Search is down",
115+
/* More options... */
116+
}
117+
```
118+
119+
**Use cases**: User communication, incident identification, status page clarity.
120+
</ResponseField>
121+
122+
<ResponseField name="description" type="string" required>
123+
A detailed description of the incident. Provides context to users about what's happening and potential impact.
124+
125+
**Usage:**
126+
127+
```ts highlight={3-4}
128+
const incidentTrigger: IncidentTrigger = {
129+
service: searchService,
130+
description:
131+
"Some users experience issues with the product search. We're investigating.",
132+
/* More options... */
133+
}
134+
```
135+
136+
**Use cases**: User communication, incident context, expectation setting.
137+
</ResponseField>
138+
139+
<ResponseField name="notifySubscribers" type="boolean" required>
140+
Whether to notify status page subscribers when the incident is triggered. When `true`, subscribers receive notifications via their configured channels.
141+
142+
**Usage:**
143+
144+
```ts highlight={3}
145+
const incidentTrigger: IncidentTrigger = {
146+
service: searchService,
147+
notifySubscribers: true,
148+
/* More options... */
149+
}
150+
```
151+
152+
**Use cases**: Proactive user communication, incident awareness, stakeholder updates.
153+
</ResponseField>
154+

‎constructs/playwright-check.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ new PlaywrightCheck("critical-e2e-monitor", {
5656
The Playwright Check Suite configuration consists of specific Playwright Check Suite options and inherited general monitoring options.
5757

5858
<Tabs>
59-
<Tab title="URL Monitor">
59+
<Tab title="Playwright Check Suite">
6060

6161
| Parameter | Type | Required | Default | Description |
6262
|-----------|------|----------|---------|-------------|

‎docs.json‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -504,7 +504,8 @@
504504
"group": "Status Pages",
505505
"pages": [
506506
"constructs/status-page",
507-
"constructs/status-page-service"
507+
"constructs/status-page-service",
508+
"constructs/incident-trigger"
508509
]
509510
},
510511
"constructs/dashboard",
@@ -884,6 +885,7 @@
884885
"guides/startup-guide-detect-communicate-resolve",
885886
"guides/getting-started-with-monitoring-as-code",
886887
"guides/empowering-developers-with-checkly",
888+
"guides/communicate-availability",
887889
"guides/playwright-testing-to-monitoring",
888890
"guides/uptime-monitoring",
889891
"guides/keyword-monitoring",

‎guides/communicate-availability.mdx‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
title: Communicate User Feature Availability with Status Pages
3+
description: Learn how Checkly status pages reflect actual user experience through synthetic monitoring, not arbitrary status indicators.
4+
sidebarTitle: Communicate Feature Availability with Status Pages
5+
---
6+
7+
Most status pages are disconnected from reality. They show green uptime bars based on server pings and health checks - metrics that tell you nothing about whether users can actually complete a purchase or log in. When infrastructure looks healthy but the checkout flow is broken, those green bars become meaningless.
8+
9+
Checkly status pages go beyond reactive manual updates and infrastructure telemetry. They're powered by synthetic monitoring that simulates real user behavior, so when your status page shows "operational," it means users can actually complete their workflows.
10+
11+
## Where traditional status page setups fall short
12+
13+
Traditional status pages suffer from a fundamental problem: **they communicate infrastructure health, not user experience**. Your servers might report healthy CPU usage while users can't log in because of [an incorrectly used React feature](https://blog.cloudflare.com/deep-dive-into-cloudflares-sept-12-dashboard-and-api-outage/). Your database might show normal query times while users can't search for products. Infrastructure monitoring matters but only tells part of the story.
14+
15+
The disconnect of green status bars and broken user experience erodes trust. Users learn to ignore status pages because they've been burned before by "all systems operational" banners during outages they're actively experiencing.
16+
17+
Outages and bugs are unavoidable. Being transparent and honest about them is what matters and builds trust in your service.
18+
19+
## How Checkly status pages work
20+
21+
[Checkly status pages](/communicate/status-pages/overview) offer everything your current status page provider offers, plus integration with synthetic monitors that validate real user behavior.
22+
23+
When you connect a [Playwright Check Suite](/detect/synthetic-monitoring/playwright-checks/overview) or [Browser Check](/detect/synthetic-monitoring/browser-checks/overview) that simulates a user logging in, adding items to cart, and completing checkout, your status page reflects whether that entire flow actually works.
24+
25+
Following this approach, **your status page reflects what matters to your users.**
26+
27+
Here's how the pieces fit together:
28+
29+
1. **Synthetic monitors validate behavior** - Playwright Check Suites and Browser Checks use Playwright to simulate user actions. These aren't simple ping tests or infrastructure checks; they're validations of your service's critical user flows in a real browser.
30+
31+
2. **Services represent user-facing capabilities** - You can define services like "Checkout" or "Login" that map to how users think about your application, not your internal architecture.
32+
33+
3. **Incident automation connects the dots** - When a check fails, it can automatically open an incident on the connected service. When the check recovers, the incident resolves.
34+
35+
This means your status page shows what matters: **can users actually use your application?**
36+
37+
## Set up a status page backed by real synthetic monitoring
38+
39+
### Create services that match user expectations
40+
41+
Services should reflect how users perceive your application. Users care about "Login" working, not whether your auth microservice cluster is healthy.
42+
43+
Good service examples:
44+
- Website
45+
- User Login
46+
- Payments
47+
- Search
48+
49+
Avoid internal naming like `Auth Service v2` or `Primary Database Cluster`.
50+
51+
To create a service:
52+
53+
1. Navigate to **Services** under **Communicate** in the sidebar
54+
2. Create a new service with a user-friendly name
55+
56+
![Services route showing multiple created services](/images/guides/images/status-pages-user-behavior-1.png)
57+
58+
### Connect synthetic monitors to services
59+
60+
This is where the real behavior validation happens. Each service can be connected to one or more monitors that validate its functionality.
61+
62+
<Note>
63+
Incident automation is available on Communicate Team and Enterprise plans. [View pricing](https://checklyhq.com/pricing)
64+
</Note>
65+
66+
1. Open your Playwright Check Suite or Browser Check from the home dashboard
67+
2. Click **Edit** in the check overview page
68+
3. Click **Settings** and enable **Incident automation**
69+
4. Fill in the incident name and initial status update
70+
5. Select which service the incident should be opened on
71+
6. Save your check
72+
73+
![Incident automation configuration of a Playwright Check Suite](/images/guides/images/status-pages-user-behavior-2.png)
74+
75+
### Create the status page
76+
77+
1. Go to **Status pages** under **Communicate** in the sidebar
78+
2. Create a new status page
79+
3. Enter a name for your page
80+
4. Add cards and assign services to them. Group related services on the same card to show average uptime
81+
5. Configure domain settings and your status page's appearance
82+
6. Click **Create status page**
83+
84+
![Status page connecting to user experience services](/images/guides/images/status-pages-user-behavior-3.png)
85+
86+
Your status page now displays real-time availability based on actual user behavior validation.
87+
88+
![Created Checkly Status Page](/images/guides/images/status-pages-user-behavior-4.png)
89+
90+
### Automate everything with Monitoring as Code
91+
92+
Checkly's [Monitoring as Code](/guides/getting-started-with-monitoring-as-code) approach enables you to automate the entire flow of creating status pages, connecting services, and configuring checks.
93+
94+
<Accordion title="View code example">
95+
96+
```ts highlight={10-13,15-25,27-35,44}
97+
import {
98+
Frequency,
99+
IncidentTrigger,
100+
PlaywrightCheck,
101+
StatusPage,
102+
StatusPageService,
103+
} from "checkly/constructs";
104+
105+
// 1. Create a new service to group checks and trigger incidents
106+
const searchService = new StatusPageService("search-service", {
107+
name: "Search Service",
108+
})
109+
110+
// 2. Create a new status page and connect the service
111+
new StatusPage("company-status", {
112+
name: "User Experience Status",
113+
url: "ux-status",
114+
cards: [
115+
{
116+
name: "User Experience",
117+
services: [searchService],
118+
},
119+
],
120+
})
121+
122+
// 3. Configure your incident automation
123+
const searchIncidentTrigger: IncidentTrigger = {
124+
service: searchService,
125+
severity: "MINOR",
126+
name: "Search is down",
127+
description:
128+
"Some users experience issues with the product search. We're investigating.",
129+
notifySubscribers: true,
130+
}
131+
132+
// 4. Assign your incident automations to checks and monitors
133+
new PlaywrightCheck("playwright-check-suite", {
134+
name: "Search Monitoring",
135+
playwrightConfigPath: "../playwright.config.ts",
136+
activated: true,
137+
pwProjects: ["Search Monitoring"],
138+
locations: ["us-east-1", "eu-west-1", "ap-southeast-2"],
139+
frequency: Frequency.EVERY_10M,
140+
triggerIncident: searchIncidentTrigger,
141+
})
142+
```
143+
144+
</Accordion>
145+
146+
## Why this approach works
147+
148+
**A status page backed by synthetic monitoring builds trust because it tells the truth.** When users see "operational," they can trust that the application actually works. When there's an incident, they know about it immediately.
149+
150+
This transparency has practical benefits:
151+
152+
- **Reduced support load** - Users check the status page instead of contacting support
153+
- **Faster incident response** - Automated incident creation means faster communication
154+
- **Accurate SLA reporting** - Uptime calculations reflect real user experience
155+
156+
<Tip>[Learn how service uptime is calculated](/communicate/status-pages/overview#service-uptime) with automated incidents.</Tip>
157+
158+
When your status page answers "can I use this?" instead of "are the servers up?", users pay attention.
159+
160+
## Further reading
161+
162+
- [Status Pages Overview](/communicate/status-pages/overview) - Complete reference for status page features
163+
- [Incident Management](/communicate/status-pages/incidents) - Detailed guide to creating and managing incidents
164+
- [Subscriber Notifications](/communicate/status-pages/subscriber-notifications) - Set up email notifications for status changes
165+
- [Anatomy of a Status Page](/learn/incidents/anatomy-of-a-status-page) - What users expect from status pages

0 commit comments

Comments
 (0)