PageSpeed
How Telescope monitors website performance using Google PageSpeed Insights (Lighthouse scores and Core Web Vitals).
PageSpeed monitors measure website performance by calling the Google PageSpeed Insights API v5, which runs a Lighthouse audit and returns category scores plus Core Web Vitals.
How a check works
- Telescope resolves the URL from the monitor's
urlfield (validated vianew URL()). - For each configured strategy (
mobile,desktop, or both), an API call is made to the PageSpeed Insights API v5. - Strategies run sequentially with a 500ms delay between calls to avoid rate limiting.
- Each API response is parsed: Lighthouse category scores (0–1 floats → 0–100 integers) and Core Web Vitals audit metrics.
- When running both strategies, the worst (minimum) score per category is used for threshold comparison.
- The overall status is determined by comparing worst scores against configured thresholds.
Checks never hang — each API call uses AbortSignal.timeout() with a full 2-minute timeout per strategy (the strategies run sequentially, so the two-strategy worst case is ~4 minutes plus the inter-strategy delay). If a strategy fails, the check returns down with any partial results preserved.
Status classification
| Condition | Status | What it means |
|---|---|---|
| All category scores >= thresholds | Up | Site performance meets expectations |
| Any category score < threshold | Degraded | Site is reachable but underperforming |
| API error, timeout, or network failure | Down | Unable to complete the audit |
| No URL configured | Down | Monitor misconfigured |
The degraded status (not down) is used for below-threshold scores because the site is still reachable — it's just slow or has quality issues.
Lighthouse categories
| Category | API key | What it measures |
|---|---|---|
| Performance | performance | Loading speed, interactivity, visual stability |
| Accessibility | accessibility | Screen readers, ARIA, color contrast, keyboard navigation |
| Best Practices | best-practices | HTTPS, no deprecated APIs, correct image aspect ratios |
| SEO | seo | Meta tags, crawlability, structured data |
Scores are 0–100, converted from the API's 0–1 float format (e.g. 0.934 → 93).
Core Web Vitals
| Metric | Audit ID | Unit | Good | Needs Improvement | Poor |
|---|---|---|---|---|---|
| First Contentful Paint (FCP) | first-contentful-paint | ms | ≤ 1,800 | 1,800–3,000 | > 3,000 |
| Largest Contentful Paint (LCP) | largest-contentful-paint | ms | ≤ 2,500 | 2,500–4,000 | > 4,000 |
| Total Blocking Time (TBT) | total-blocking-time | ms | ≤ 200 | 200–600 | > 600 |
| Cumulative Layout Shift (CLS) | cumulative-layout-shift | unitless | ≤ 0.1 | 0.1–0.25 | > 0.25 |
| Speed Index (SI) | speed-index | ms | ≤ 3,400 | 3,400–5,800 | > 5,800 |
| Time to Interactive (TTI) | interactive | ms | ≤ 3,800 | 3,800–7,300 | > 7,300 |
CLS is stored with 3 decimal places. All other metrics are in milliseconds. Missing audits are stored as null.
Configuration options
| Setting | Default | Description |
|---|---|---|
| Strategy | Both (mobile + desktop) | Which strategies to run: mobile, desktop, or both |
| Min Performance Score | 50 | Minimum acceptable performance score (0–100) |
| Min Accessibility Score | 50 | Minimum acceptable accessibility score (0–100) |
| Min Best Practices Score | 50 | Minimum acceptable best practices score (0–100) |
| Min SEO Score | 50 | Minimum acceptable SEO score (0–100) |
| Per-strategy timeout | 2 minutes | Fixed timeout per API call — each strategy gets a full 2 minutes |
API key
The PageSpeed Insights API works without an API key but has lower rate limits (roughly 25 requests/100 seconds per IP). To increase limits:
- Create a Google Cloud project and enable the PageSpeed Insights API.
- Generate an API key in the Google Cloud Console.
- Set the
GOOGLE_API_KEYenvironment variable on the worker.
With an API key, the limit increases to roughly 400 requests/100 seconds.