Skip to content

feat(browser): Add bfcacheIntegration - #22397

Open
logaretm wants to merge 15 commits into
developfrom
awad/bfcache-integration
Open

feat(browser): Add bfcacheIntegration#22397
logaretm wants to merge 15 commits into
developfrom
awad/bfcache-integration

Conversation

@logaretm

@logaretm logaretm commented Jul 20, 2026

Copy link
Copy Markdown
Member

Adds an opt-in bfcacheIntegration that reports back/forward-cache health as metrics: a hit/miss navigation counter, the (Chromium-only) notRestoredReasons behind a miss, and the fallback reload cost on a miss.

Metrics are the source of truth rather than spans, because a bfcache hit restores an existing page and never creates a pageload span, so span-only instrumentation would drop every successful restore from the dataset.

New Metrics

Three metrics, all under the browser.bfcache.* namespace.

metric type emitted key attributes answers
browser.bfcache.navigation counter 1 per back/forward navigation browser.bfcache.outcome (hit/miss), browser.bfcache.not_restored_reason_count (miss only) hit/miss rate (total = ungrouped sum; hit% = outcome:hit / total)
browser.bfcache.not_restored counter 1 per reason (a miss can emit several) browser.bfcache.reason (verbatim), browser.bfcache.frame (top/child) which blockers, and where (top document vs a child/embed)
browser.bfcache.reload.duration distribution (ms) 1 per miss the cost of a miss

Conventions PR is here getsentry/sentry-conventions#513

An example of a dashboard that uses bfcache metrics would look like this:

CleanShot 2026-07-20 at 14 12 41@2x

We can pre-ship a sentry-provided dashboard to onboard users to this feature.

Resources

@logaretm logaretm changed the title awad/bfcache integration feat(browser): Add bfcacheMetricsIntegration Jul 20, 2026
@logaretm
logaretm force-pushed the awad/bfcache-integration branch from 59903b5 to f7104d6 Compare July 20, 2026 18:20
@logaretm
logaretm force-pushed the awad/bfcache-integration branch from f7104d6 to fc820d3 Compare July 20, 2026 18:30
@logaretm
logaretm force-pushed the awad/bfcache-integration branch from 4cb315e to 04c860f Compare August 4, 2026 14:06
@github-actions

github-actions Bot commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

size-limit report 📦

Path Size % Change Change
@sentry/browser 29.83 kB - -
@sentry/browser - with treeshaking flags 28.03 kB - -
@sentry/browser (incl. Tracing) 47.25 kB - -
@sentry/browser (incl. Tracing + Span Streaming) 47.27 kB - -
@sentry/browser (incl. Tracing, Profiling) 52 kB - -
@sentry/browser (incl. Tracing, Replay) 86.59 kB - -
@sentry/browser (incl. Tracing, Replay) - with treeshaking flags 76.01 kB - -
@sentry/browser (incl. Tracing, Replay with Canvas) 91.28 kB - -
@sentry/browser (incl. Tracing, Replay, Feedback) 103.95 kB - -
@sentry/browser (incl. Feedback) 47.13 kB - -
@sentry/browser (incl. sendFeedback) 34.67 kB - -
@sentry/browser (incl. FeedbackAsync) 39.78 kB - -
@sentry/browser (incl. Metrics) 30.91 kB - -
@sentry/browser (incl. Logs) 31.14 kB - -
@sentry/browser (incl. Metrics & Logs) 31.81 kB - -
@sentry/react 31.63 kB - -
@sentry/react (incl. Tracing) 49.51 kB - -
@sentry/vue 34.92 kB - -
@sentry/vue (incl. Tracing) 49.24 kB - -
@sentry/svelte 29.86 kB - -
CDN Bundle 31.87 kB - -
CDN Bundle (incl. Tracing) 47.54 kB - -
CDN Bundle (incl. Logs, Metrics) 33.41 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) 48.95 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) 72.75 kB - -
CDN Bundle (incl. Tracing, Replay) 85.18 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) 86.5 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) 91.01 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) 92.31 kB - -
CDN Bundle - uncompressed 94.62 kB - -
CDN Bundle (incl. Tracing) - uncompressed 142.12 kB - -
CDN Bundle (incl. Logs, Metrics) - uncompressed 99.24 kB - -
CDN Bundle (incl. Tracing, Logs, Metrics) - uncompressed 146.1 kB - -
CDN Bundle (incl. Replay, Logs, Metrics) - uncompressed 223.94 kB - -
CDN Bundle (incl. Tracing, Replay) - uncompressed 261.38 kB - -
CDN Bundle (incl. Tracing, Replay, Logs, Metrics) - uncompressed 265.34 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback) - uncompressed 275.08 kB - -
CDN Bundle (incl. Tracing, Replay, Feedback, Logs, Metrics) - uncompressed 279.04 kB - -
@sentry/nextjs (client) 52.08 kB - -
@sentry/sveltekit (client) 47.71 kB - -
@sentry/core/server 65.52 kB - -
@sentry/core/browser 51.88 kB - -
@sentry/node 120.24 kB +0.01% +1 B 🔺
@sentry/node/import (ESM hook with diagnostics-channel injection) 0 B added added
@sentry/node - without tracing 83.69 kB +0.01% +1 B 🔺
@sentry/aws-serverless 92.35 kB - -
@sentry/cloudflare (withSentry) - minified 218.65 kB - -
@sentry/cloudflare (withSentry) 538.85 kB - -

View base workflow run

logaretm added 12 commits August 6, 2026 13:45
Add an opt-in browser integration that tracks back/forward cache health
as metrics:

- browser.bfcache.navigation: hit/miss counter by navigation type
- browser.bfcache.not_restored: Chromium notRestoredReasons per miss
- browser.bfcache.miss.reload.duration: fallback reload cost on a miss

Hits are detected via pageshow.persisted; misses via a back_forward
navigation entry. Includes unit tests for the notRestoredReasons parser
and a Playwright suite for hit/miss detection.
Adds a dedicated `browser-bfcache` e2e app that exercises
`bfcacheMetricsIntegration` against a genuine back/forward cache: real
cross-document navigation served by `vite preview`, restored via
renderer-initiated `history.back()`, under the full Chrome-for-Testing
binary (`channel: 'chromium'`) with the disable flag stripped and
`BackForwardCache` enabled.

Covers hits, misses with real `notRestoredReasons`, and deliberately
bfcache-ineligible pages via `?botch=`: an `unload` listener (stable
blocker) and an open WebSocket (blocks only before Chrome 149, so that
assertion is version-gated). `Cache-Control: no-store` no longer blocks.

Removes the simulated browser-integration bfcache suite, which faked the
restore with a synthetic `pageshow` and a manual flush; it is superseded
by the real assertions here. The reason-parser unit test stays.
The unload miss deterministically also yields a privacy-masked reason.
Assert the integration reports it as a `masked` frame, giving real-browser
coverage of the masked-frame classification path (previously only unit-tested).
A plain open IndexedDB connection (and even an in-flight transaction) no
longer blocks bfcache in current Chrome, contrary to web.dev's list. The
condition that still blocks is a connection holding up a version upgrade,
which yields an `idbversionchangeevent` reason. Add a deterministic e2e
case for it and document how real Chrome diverges from the article.
A no-store (CCNS) page is only evicted from bfcache once a cookie changes;
neither the header nor a cookie change blocks on its own. Add a `?botch=nostore`
case that serves the document with `Cache-Control: no-store` (via a preview
middleware, since a static server can't set per-request headers) and mutates a
cookie, asserting the `response-cache-control-no-store` reason.

Also trim the version-specific blocker details from the README so they don't
drift; the botch cases and their assertions are the source of truth.
`browser.bfcache.navigation_type` was 1:1 with `browser.bfcache.outcome`
(hit <-> back-forward-cache, miss <-> back-forward), so it added a second
attribute encoding the same bit. Keep only `outcome`; navigation-type
vocabulary belongs on web-vital samples (future soft-navigation work), not
on bfcache counters. Also drops an unnecessary PageTransitionEvent cast.
Adds two real-browser e2e cases: an embedded bfcache-eligible iframe keeps
the top page restorable (hit), and an iframe with an unload listener makes
the top page ineligible with the reason reported from the child frame. This
gives the `frame: 'child'` classification real coverage (previously unit-only).
`frame` no longer special-cases the `masked` reason value; it now reflects
only the frame's position in the notRestoredReasons tree (`top`/`child`).
The `masked` value already lives on the `reason` attribute, so tagging the
frame as `masked` too was redundant. The integration no longer inspects any
reason string - reasons pass through verbatim.
…utes

Undefined attribute values are dropped downstream, so assign them
directly instead of spreading conditional objects. Use the
SENTRY_SEGMENT_NAME constant from @sentry/conventions for the route
attribute instead of a hardcoded string.
Capping the not-restored reasons by default silently dropped data, so a
page blocked for more reasons than the cap looked cleaner than it was.
Report every reason by default and treat `maxReasons` as an opt-in cap.

The platform bounds `notRestoredReasons` to a small standardized set per
navigation, so reporting all carries no realistic cardinality risk. A cap
below 1 drops everything, so clamp it to 1 and warn on debug builds.
…on name

Compute the transaction name once per pageshow and thread it through the
metric helpers instead of re-reading the scope for each metric. Extract
the not-restored reason emission into its own helper and correct the
pageshow event type.
…tion

Name the integration after what it observes, consistent with
webVitalsIntegration and the rest of the integration exports. bfcache is
the platform term, spelled lowercase as one word.
@logaretm
logaretm force-pushed the awad/bfcache-integration branch from fe28e7c to 4f2cec5 Compare August 6, 2026 17:45
@logaretm

logaretm commented Aug 6, 2026

Copy link
Copy Markdown
Member Author

bugbot run

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Cursor Bugbot has reviewed your changes and found 3 potential issues.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 4f2cec5. Configure here.

Comment thread packages/browser/src/integrations/bfcache.ts
Moves the pageshow registration from per-client setup to setupOnce so a
single listener is registered regardless of how many clients are created,
avoiding duplicate bfcache metrics on reinitialization.
…nd miss

Covers three segment-name behaviors: a hit carries the parameterized route
still on the scope after the freeze, a hit without a routing integration
falls back to the raw pathname, and a miss reload falls back to the reloaded
page's pathname rather than any pre-freeze route.
@logaretm
logaretm marked this pull request as ready for review August 6, 2026 21:16
@logaretm
logaretm requested a review from a team as a code owner August 6, 2026 21:16
@logaretm
logaretm requested review from Lms24 and msonnb and removed request for a team August 6, 2026 21:16
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.

1 participant