jantimon / jantimon/web-performance-debugger

wpd 2.0: planned user value

Open
#173 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
31
Forks
1
Avg merge
1h 18m
Merged PRs (30d)
2

Description

Tracking issue for 2.0. 2.0 is a batch: every breaking change waits here and ships together, so users re-record baselines once. Non-breaking work keeps shipping as 1.x.

## What 2.0 adds for users

### 1. `--deep` on heavy production pages (the 512MB ceiling goes away)
Today a `--deep` trace of a heavy page can exceed what one JSON string holds (~512MB); wpd refuses, so heavy pages are limited to one iteration. 2.0 moves the deep event log out of the recording into an indexed SQLite sidecar (Node's built-in `node:sqlite`, no new dependency):

- Deep logs of 4-10GB become normal, so multi-iteration `--deep` on real landing pages works.
- Drills (`query get`, `query events`, stored blame) become indexed lookups, not a full-file parse.
- The main recording stays digest-sized on every capture mode; agents keep reading it whole.
- JSON stays compatible where promised, at the `query … --format json|toon` verbs. A streaming NDJSON export covers plain-text interop.

Status: **probed, design final.** Measured on Node 24 / SQLite 3.50.4: RSS stays flat at 84-125MB while writing a 4-10GB index, where the current one-string format throws at ~478k events; drills drop from seconds to sub-millisecond (point lookup 0.13ms vs 2.4s, range 46ms vs 11s). Full probe: [docs/dev/deep-log-storage.md](docs/dev/deep-log-storage.md); background: [docs/dev/trace-buffer.md](docs/dev/trace-buffer.md).

### 2. Small breaking cleanups riding the batch
- Rename the three `*Provenance` exported type names (`GroupSpansProvenance` and siblings). The word is gone from every doc and comment; the type names follow now that a breaking release ships anyway.
- Split usage errors onto exit code 2. Today exit 1 means a blown gate, a mistyped flag, and a missing file alike, so a caller gating on `assert` cannot tell a regression from a bad invocation. 2.0: **0** pass, **1** measured failure (gate fired, n/a FAIL, comparability refusal), **2** wrong invocation (unknown flag, missing argument, unreadable file). Contained in `src/cli.ts`'s error paths plus commander's `exitOverride`.

### 3. Considered and declined
- Renaming `routeLcp`/`routeCls`/`routeInpMs` to the ecosystem's soft-nav names (web-vitals v6, Lighthouse 13.4, PSI). The `route*` names say what is measured, not which API measured it, so they stay; a README note mapping the two names will do. Joins the batch only if the ecosystem names harden against us. Background: [docs/dev/navigation-and-lcp.md](docs/dev/navigation-and-lcp.md).

## What 2.0 is not
No new measurement semantics: the trust tiers, refusal behavior, and comparability gates carry over unchanged. How every number is verified: [docs/verification.md](docs/verification.md).

## Migration (known today)
- Old recordings refuse to open with a re-record message (the schema-epoch rule, [README: Stability and versioning](README.md#stability-and-versioning)); re-record stored baselines once after upgrading.
- CLI commands and flags: no removals planned.
- Raw-JSON consumers of the deep `events[]` array switch to the query verbs or the NDJSON export.
- Consumers importing the `*Provenance` type names update the imports; the shapes are unchanged.
- Scripts branching on exit `== 1` treat exit 2 as a usage error; scripts branching on `!= 0` are unaffected.

Contributor guide

Open the contributing guide

Research direction

Start with docs/dev/deep-log-storage.md and docs/dev/trace-buffer.md to understand the proposed deep-log storage design, then inspect the CLI error paths in src/cli.ts and the commander's exitOverride handling. Review the migration notes and verification guidance before deciding which part to take; done means the selected 2.0 behavior, compatibility expectations, and relevant verification are complete.

Written by the indexing model from the issue text.

Assessment

Tech stack
node.js, sqlite, typescript
Domain
cli, databases, performance, release
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.