Skip to content

Explain incomplete Chrome trace recordings - #15

Merged
jackfranklin merged 5 commits into
ChromeDevTools:mainfrom
kurtextrem:codex/trace-capture-diagnostics
Nov 19, 2026
Merged

jackfranklin merged 5 commits into
ChromeDevTools:mainfrom
kurtextrem:codex/trace-capture-diagnostics

Conversation

@kurtextrem

@kurtextrem kurtextrem commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

View just this PR’s diff

This series comes from a fork. GitHub requires all branches in a native stack to be in the same repository.

The agent skill explains how to record a trace. The CLI gives recapture guidance when parsing fails for missing frames or when an overview finds no main page frame. Use scan to search raw events from an existing recording. The overview explains how to capture missing CPU samples. For navigation recordings with no layout shifts or loading-category events, it reports CLS as unavailable and suggests checking the CDP capture categories. A recording with no navigation or shifts can report zero CLS.

Synthetic regression tests cover the missing-frame error, capture warnings, and zero CLS in a recording without navigation.

Part 1 of 5 for #14. Papercuts 1 and 3.

Fixes the missing DevTools and CDP recording guidance requested in #9.

@jackfranklin jackfranklin left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for putting this stack together! Overall this looks solid and very close to mergeable. A few small points to check before marking ready for review:

  1. Possible false positive in hasLayoutShiftData() on mid-session traces: Checking for LayoutShift or loading-category events works well for page-load traces, but on a legitimate DevTools recording of an already-loaded page (e.g., an interaction-only trace with no navigations, network requests, or layout shifts), there may be no loading-category events at all. In that case overview would report cls: null and emit a recapture warning even though CLS is genuinely 0. It might be worth softening the warning wording (or scoping the check to traces with navigations / checking trace config if available).
  2. Avoid per-event array allocations in hasLayoutShiftData(): event.cat.split(',').includes('loading') allocates an array for every event in rawEvents when no loading events are present, which can be expensive on large traces (hundreds of thousands of events). A regex or substring check without split(',') would avoid that overhead.
  3. Formatting / checks: CI doesn't currently run npm run check / npm test on fork PRs—could you double-check that npm run check (Biome formatting/linting) and npm test pass cleanly? A couple of spots (e.g., hasLayoutShiftData in src/engine/helpers.ts and the JSON.stringify([{ ... }]) calls in the tests) look like Biome might want to reformat them.

@kurtextrem
kurtextrem marked this pull request as ready for review November 19, 2026 13:14
@jackfranklin
jackfranklin merged commit 3c71b26 into ChromeDevTools:main Nov 19, 2026
6 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants