ColoredCow / ColoredCow/performance-adapter-wp
Automatic root-cause attribution for page-load spikes (GTmetrix data currently unused)
- Dominant language
- PHP
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
Today, when the "Fully Loaded Time" trend spikes on the dashboard, there is no way to know why without manual investigation — opening the individual GTmetrix report for that test, reading its Top Issues list, and scrolling through the raw waterfall to find the specific request responsible.
This was confirmed directly this week: two spikes (July 16 and July 19, both ~30s Fully Loaded Time despite normal traffic and unchanged page weight/DOM size) took a full manual walkthrough of two separate GTmetrix reports to trace back to a single cause — a failed request to a third-party tracking script (`pixel.js`) that hung for ~29-30 seconds before failing, while the actual customer-facing metrics (LCP, FCP) stayed normal the whole time.
None of that diagnostic path exists on the dashboard. The dashboard only shows that a spike happened — never what caused it.
## What's actually needed
The diagnostic data already exists — GTmetrix generates a "Top Issues" list and a full per-request waterfall (including failed/slow requests) for every test. It's just not being captured into BigQuery today; it only exists on GTmetrix's own report page, which is why this required manual investigation.
Root-cause attribution does not require AI or manual review once this data is captured. A deterministic rule against structured data is enough, e.g.:
```
IF fully_loaded_time is significantly higher than LCP for that test
AND a request in that test's data has status = "failed" OR duration > threshold
THEN attribute the spike to: [request URL], [status/duration]
```
## Proposed steps
1. **Confirm GTmetrix API access** — verify whether the Top Issues list and per-request waterfall/failure data are available via the GTmetrix API at the current plan tier (not just the website UI). This gates everything else.
2. **Capture this data into BigQuery** alongside the existing per-test metrics (GTmetrix score, LCP, TTFB, CLS, Fully Loaded Time).
3. **Build the attribution rule** above, surfaced directly next to the Fully Loaded Time chart — so a spike shows "caused by: [X]" instead of an unexplained line going up.
4. **Distinguish customer-facing metrics from full-completion metrics on the same view** — LCP/FCP (what customers actually experience) should be shown alongside Fully Loaded Time, so a spike caused by a background/non-blocking request (like a failed tracking pixel) doesn't read as "the site was down for 30 seconds" when customers never noticed anything.
## Why this matters
Without this, every spike requires manual detective work, which doesn't scale and isn't something that can be sold as an automated monitoring capability. This is one of the most repeated pieces of feedback across every review of the tool so far — the dashboard shows that something changed, never why, or what to do about it.
## Acceptance criteria
- [ ] Confirmed whether GTmetrix API exposes Top Issues + per-request failure/duration data at current plan tier
- [ ] Top Issues and relevant waterfall data captured into BigQuery per test run
- [ ] Deterministic attribution rule built and surfaced on the dashboard next to the Fully Loaded Time chart
- [ ] LCP/FCP shown alongside Fully Loaded Time so customer-facing impact vs. background/non-blocking failures are visually distinguishable
- [ ] Verified against the July 16 and July 19 test data specifically — dashboard should now show "caused by: failed request to track.megafitmeals.com/pixel.js" instead of an unexplained spike
## Note on repo scope
This work is on the GTmetrix/frontend collection pipeline, not the WordPress DB-health plugin — it may belong in the `performance-dashboard` repo depending on where that pipeline actually lives. Filed here for now since it's the accessible repo; move if needed.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by confirming whether the GTmetrix API exposes Top Issues and per-request waterfall data at the current plan tier, then identify where the GTmetrix/frontend collection pipeline and BigQuery storage live; the issue notes this may belong in another repository. Done means capturing the data, surfacing deterministic attribution beside the Fully Loaded Time chart, showing LCP/FCP alongside it, and verifying the July 16 and July 19 examples.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- google-cloud, php
- Domain
- analytics, cloud, performance
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100