ColoredCow / ColoredCow/performance-adapter-wp

DB health has no root-cause report — we see the trend but not why it moved or what to fix

Open
#45 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
PHP
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

## Problem

We show the Query Execution Time trend, but we have no clue why there's a spike or a dip on any given day, and no indication of what actually needs to be fixed.

This is a bigger gap than it looks, because of a direct comparison: **page health has a full report per test — DB health doesn't.** For frontend performance, every GTmetrix test produces a detailed report: Top Issues, a full request waterfall, exact numbers for what's slow and why. When a page-load spike happens, we can open that report and find the actual cause (this is exactly how the July 16/19 page-load spikes were traced back to a specific failed tracking request).

For DB health, there is no equivalent. The QET chart shows a number moving up or down — for example a dip to 647ms on July 22 against a normal range of 1,300-1,700ms — and that's the entire artifact. There's no report to open, no breakdown to inspect, nothing that explains the swing or tells us what to act on.

## Why this is a different kind of gap than the frontend one (issue #44)

For a page load, there are many sub-requests to inspect (images, scripts, third-party calls) — a waterfall report makes sense. For QET, the query itself is fixed and identical every day (the same COUNT/JOIN against orders older than the retention window) — so there's no waterfall of sub-requests to look at. What's missing instead is context about the *conditions* the query ran under:

- **InnoDB buffer pool state** — if relevant data pages were already cached from a recent read, the same query runs faster with nothing meaningfully different about database health.
- **DB server load at the exact test moment** — fewer concurrent connections/queries at that instant means a faster response, unrelated to actual database health.
- **Query plan / index changes** — if InnoDB stats were recently recalculated (see issue #43), the query planner can pick a different execution plan run to run.

None of this is captured today, so every swing — up or down — is unexplainable without manual speculation, and there's no equivalent of a GTmetrix report to check instead.

## Proposed fix

Build a DB-health equivalent of the page-health report:

1. **Capture server-state context** alongside every QET reading — connection count, buffer pool hit ratio, whether stats were recently recalculated.
2. **Store this as a "report" per test run**, not just a single number — so a specific day's DB health test can be opened and inspected the same way a GTmetrix report can be opened for a specific page-load test.
3. **Surface an explanation and a recommendation next to the QET chart** — e.g. "QET dropped because buffer pool hit ratio was unusually high that run" or "QET rose because 40 concurrent connections were active — no action needed" vs. "QET rose because InnoDB stats were just recalculated and query plan changed — investigate."

## Acceptance criteria

- [ ] Each QET test run produces a stored report (not just a single number) — capturing connection count, buffer pool hit ratio, and recent-stats-recalculation status at the moment it ran
- [ ] Dashboard surfaces a plain-language explanation and recommendation next to the QET chart for any notable swing, mirroring how page health surfaces Top Issues per test
- [ ] Verified against a real historical swing (e.g. the July 22 dip) to confirm the captured report actually explains it and tells us what, if anything, needs fixing

## Related

- Issue #43 — stale DB size readings / InnoDB stats lag (same underlying InnoDB behavior, different symptom)
- Issue #44 — automatic root-cause attribution for frontend spikes (same category of problem, different mechanism — page health has a report to inspect; DB health currently has none)

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading the existing QET chart and test-run flow, then compare how page health stores and surfaces GTmetrix reports; the issue does not name specific files or tests. Review related issues #43 and #44 for context. Done means each QET run stores the specified server-state context, the dashboard explains notable swings with recommendations, and the result is checked against a historical swing such as the July 22 dip.

Written by the indexing model from the issue text.

Assessment

Tech stack
mysql, php, wordpress
Domain
databases, observability
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.