Uptime & Response Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Uptime and Response Tracking is a core functional module of StatusBeam designed to monitor service health, record time-series performance data, and visualize historical trends. The system probes services via a Cloudflare Cron Worker, aggregates the results into Cloudflare D1 (history) and KV (current snapshot), and renders the data through an Astro-based frontend at the edge.
The system focuses on two primary metrics: Uptime, represented as a percentage of successful probes over specific windows (24h, 7d, 30d, 90d), and Response Time, measured as round-trip latency in milliseconds. These metrics are presented to users via high-density 90-day uptime bars and interactive response-time sparklines. Sources: ARCHITECTURE.md:12-20, README.md:95-125
Data Architecture & Lifecycle
The tracking lifecycle follows a "Check → Store → Render" flow. Probes are initiated by a Cron Trigger which executes the check logic, determines the status based on response codes and latency, and persists the resulting CheckResult objects.
The diagram shows the flow from cron execution to visual rendering on the status page. Sources: ARCHITECTURE.md:75-84
Core Data Structures
The domain model defines specific interfaces for tracking health and performance:
| Structure | Description | Key Fields |
|---|---|---|
CheckResult | Raw verdict of a single probe. | status, code, responseTime, checkedAt |
DayStat | Aggregated outcome for a 24-hour UTC window. | date, status, uptime (0..1) |
ResponsePoint | Single latency sample for trend visualization. | at, ms |
SiteSummary | Final aggregated state for frontend consumption. | status, uptimeDay, uptimeMonth, history |
Sources: packages/core/src/types.ts:13-64
Uptime Calculation Logic
Uptime is derived from the status of individual checks. A site is considered "up" if the HTTP request completes with an expected status code and the response time is within the configured maxResponseTime. Sources: packages/core/src/check.ts, packages/core/src/types.ts:67-75
Window Aggregation
The system calculates uptime ratios across different time windows by averaging DayStat values while ignoring days with no data.
export function windowUptime(history: DayStat[]): number {
const days = history.filter(d => d.status !== null)
if (days.length === 0) {
return 1
}
return days.reduce((sum, d) => sum + d.uptime, 0) / days.length
}
Sources: packages/core/src/types.ts:81-88
A ratio is then formatted for display. To maintain accuracy while avoiding misleading "100.00%" labels for near-perfect uptime, any value $\ge$ 99.995% is collapsed to "100%". Sources: packages/core/src/types.ts:91-95, packages/core/src/types.test.ts:46-53
Response Time Analysis
Response time tracking provides insight into latency trends beyond simple binary up/down status. The system collects responseTime in milliseconds for every successful probe. Sources: packages/core/src/types.ts:20-22
Statistical Rollups
To provide meaningful summaries, the core package implements several statistical functions:
- Average Response: Calculates the mean latency over a sample window, rounded to the nearest integer. Sources: packages/core/src/types.ts:98-104
- Percentile Response (p95): Uses a nearest-rank algorithm to determine the p-th percentile (e.g., 0.95 for p95), which is more resilient to outliers than a simple average. Sources: packages/core/src/types.ts:110-120
Visualization Components
The frontend utilizes React islands within the Astro site to render dense tracking data efficiently.
Uptime Timeline
The UptimeTimeline component renders a 90-day bar chart. Each bar represents one DayStat.
- Color Coding: Uses CSS variables for status:
bg-status-operational(green),bg-status-degraded(yellow),bg-status-major(red), andbg-status-nodata(gray). - Interactivity: Each bar includes a native
titleattribute displaying the date, status, and specific uptime percentage for that day.
Sources: apps/web/src/components/UptimeTimeline.tsx:7-35
Response Chart
The ResponseChart (referenced in StatusList) visualizes the responseHistory array of ResponsePoint objects. It is accessible via a toggle in the service row that displays the current responseTime and the units (ms). Sources: apps/web/src/components/StatusList.tsx:55-78
Summary of Status Mapping
The following table describes how raw check results map to display severities and tracking states:
| Check Status | Severity Mapping | Uptime Impact | Timeline Color |
|---|---|---|---|
up | operational | Positive (1.0) | bg-status-operational |
degraded | degraded | Positive (variable) | bg-status-degraded |
down | major_outage | Negative (0.0) | bg-status-major |
null | N/A | Ignored | bg-status-nodata |
Sources: packages/core/src/types.ts:67-77, apps/web/src/components/UptimeTimeline.tsx:7-12
Uptime and Response Tracking ensures that service performance is not only monitored in real-time but also historically preserved, allowing users to verify Service Level Agreements (SLAs) and observe latency patterns over time. This data is critical for the "Overall-status banner" which rolls up the worst component state for a unified health view. Sources: README.md:143-155