# QuantumCache – Benchmark Methodology

## Purpose

Measure QuantumCache (QC) impact on anonymous (non-logged-in) requests under controlled, repeatable configurations.

Each configuration is compared to its own baseline (QuantumCache disabled, same object-cache state).
Metrics capture median (p50) and 95th-percentile (p95) **time-to-first-byte (TTFB)** and total request time, expressed as percentage deltas versus baseline.

---

## Folder contents

* `qc_report_full.md` – consolidated benchmark results for QuantumCache 0.1.2
* `qc_urls.txt` – URL set used for tests (80–150 public routes)
* `methodology.md` – this document
* `raw/` – optional folder for raw wrk logs (excluded from releases)

---

## Environment

* Host OS: **Windows 11 Home (WSL 2)**
* CPU: **AMD Ryzen 9 7950X3D (16 cores / 32 threads)**
* RAM: **64 GB**
* Stack (Docker Compose):

  * `wordpress:6.8-php8.2-apache`
  * `mysql:8.0`
  * `redis:7.2`
* WordPress: 6.8 RC (stable channel)
* PHP: 8.2
* Object cache drop-in: **disabled for published tests**
* QC version: **0.1.2**
* MU plugins for diagnostics: `qc-guard`, `qc-store-guard`, `qc-profiler`, `qc-diag`
* All requests: anonymous GET to `http://localhost:8080`

---

## URL set

`docs/benchmarks/qc_urls.txt` contains mixed routes:

```
/
 /category/news/
 /?cat=76&posts_per_page=36&paged=2
 /2025/09/sample-post/
```

Include:

* Home, archive, category/tag pages
* 40–100 singular posts/pages of mixed age
* Any custom templates in actual use

---

## Scenarios and baselines

Three configurations are benchmarked:

| Scenario | Description         | Purpose                              |
| -------- | ------------------- | ------------------------------------ |
| **B0**   | QC OFF (baseline)   | Native WordPress behavior            |
| **B1**   | QC ON – Redis store | Ideal backend, cached query paths    |
| **B2**   | QC ON – MySQL store | Portable fallback, functional parity |

### Toggle sequence

```bash
# Redis plugin disabled for all B-series tests
docker compose run --rm wpcli wp redis disable
docker compose run --rm wpcli wp option update qc_store_mode redis

# Baseline
docker compose run --rm wpcli wp plugin deactivate quantumcache

# QC Redis
docker compose run --rm wpcli wp plugin activate quantumcache

# QC MySQL
docker compose run --rm wpcli wp option update qc_store_mode mysql
```

---

## Run discipline (per run)

### 1 – Reset caches

```bash
docker compose exec wordpress bash -lc \
'php -r "require '\''/var/www/html/wp-load.php'\''; QuantumCache\\Support\\Maintenance::purge_all(); echo \"OK\n\";"'
```

### 2 – Warm once

Populate caches for warm-traffic behavior:

```bash
xargs -I{} -n1 bash -lc \
'curl -sS -o /dev/null -w "%{http_code}\n" http://localhost:8080{}' \
< docs/benchmarks/qc_urls.txt
```

Verify headers on a few manual requests:

* `X-QC-Main: HIT` on second load
* `X-QC-Store-Actual: redis | mysql` matches store
* `X-QC-OC:` off (for this dataset)

### 3 – Measure

Tool: `wrk` (or `wrk2`)
Concurrency: 16 / 32 / 64 Duration: 30 s Repeats: 8 per URL per step

Example harness:

```bash
SCEN=qc_redis      # or qc_mysql
OUT=docs/benchmarks/raw/$SCEN
mkdir -p "$OUT"

while read -r path; do
  for c in 16 32 64; do
    for i in $(seq 1 8); do
      wrk -t4 -c$c -d30s --latency "http://localhost:8080$path" \
      | tee -a "$OUT/${c}.log"
    done
  done
done < docs/benchmarks/qc_urls.txt
```

---

## Aggregation and reporting

Per (URL, concurrency):

* Take median p50 and p95 across the 8 repeats.

Per scenario vs baseline:

* Δ % = (scenario − baseline) / baseline × 100

Across all URLs:

* Report median of URL-level deltas (p50 and p95).
* Note best-route delta (largest individual gain).

Automated via `scripts/qc_full_bench.sh`, producing:

* `ttfb.tsv` – p50/p95 TTFB
* `total.tsv` – p50/p95 total times
* MySQL/Redis server deltas
* Aggregated markdown → `docs/benchmarks/qc_report_full.md`

---

## Interpretation

* **QC (Redis store)**: near-zero read latency, showing typical 70–75 % DB-query reduction versus baseline on warm requests.
* **QC (MySQL store)**: identical semantics with ~10 % higher latency, useful for hosts without Redis.
* Relative deltas, not absolute ms, are the focus—hardware varies, ratios don’t.

---

## Notes

* Use identical Docker stacks and URL sets across all runs.
* Disable cron/indexing and any traffic outside wrk.
* Run each scenario twice to confirm stability before publishing.
* `wp_options` and transient growth were monitored and showed no bloat.

---

### Omitted: Redis Object Cache Plugin Benchmarks

Earlier drafts included parallel tests with the *Redis Object Cache* drop-in enabled.
Those runs were excluded from publication because, in single-host lab environments, the plugin introduces local serialization overhead without adding measurable benefit.
QuantumCache benchmarks therefore focus solely on its own cache layer (**B0–B2 scenarios**).

---

✅ **Updated for QuantumCache v0.1.2**
Aligned with current `scripts/qc_full_bench.sh` and `qc_report_full.md`; matches the active Docker stack and testing environment.