BFCache Metrics for Browser JavaScriptBETA
Track browser back/forward cache (bfcache) health as Sentry Application Metrics.
Available since: v11.0.0
This integration only works inside a browser environment.
Import name: Sentry.bfcacheMetricsIntegration
The bfcacheMetricsIntegration tracks the health of the browser's back/forward cache (bfcache) and emits it as Sentry Application Metrics. The bfcache is a browser optimization that restores a previously visited page instantly from an in-memory snapshot when the user navigates back or forward. When the cache is hit, the back button feels instant; when it isn't, the same action becomes a full page reload.
Use this integration to answer these questions:
- What share of back/forward navigations does the browser restore instantly?
- Which routes miss the bfcache most often?
- What is blocking the browser from caching the page?
- How expensive is the fallback reload when a restore fails?
Sentry.init({
integrations: [Sentry.bfcacheMetricsIntegration()],
});
Sentry.init({
integrations: [Sentry.bfcacheMetricsIntegration()],
});
This integration requires Sentry Application Metrics to be available in your Sentry organization.
A hit is a back/forward navigation that the browser restored instantly from the bfcache; a miss is one that fell back to a full page load. Hit/miss detection works across modern Chromium, Firefox, and Safari. When a miss occurs, the SDK also records the notRestoredReasons the browser reports for it. This API is currently Chromium-only, so the SDK records misses on other browsers without reasons.
A single miss can report several not-restored reasons (for example, multiple frames can block one page). By default, the SDK emits every reported reason. Set maxReasons to cap how many it emits per miss:
Sentry.init({
integrations: [
Sentry.bfcacheMetricsIntegration({
maxReasons: 3,
}),
],
});
Sentry.init({
integrations: [
Sentry.bfcacheMetricsIntegration({
maxReasons: 3,
}),
],
});
The SDK clamps values below 1 to 1, since a lower cap would drop all reason data. This option only limits the browser.bfcache.not_restored metric and doesn't affect the reason count on browser.bfcache.navigation.
| Metric | Type | Description |
|---|---|---|
browser.bfcache.navigation | counter | One per back/forward navigation, split by outcome (hit or miss). |
browser.bfcache.not_restored | counter | One per not-restored reason on a miss. Chromium-only. |
browser.bfcache.reload.duration | distribution | Duration (in milliseconds) of the fallback reload when a back/forward navigation missed the bfcache. The SDK only emits this when the browser reports a duration. |
browser.bfcache.navigation includes:
| Attribute | Description |
|---|---|
browser.bfcache.outcome | hit if the browser restored the page from the bfcache, miss if it reloaded the page. |
browser.bfcache.not_restored_reason_count | The number of reasons the browser reported for a miss. The SDK omits this on hits and on misses where the browser reported no reasons. |
sentry.segment.name | The route the navigation landed on, which the SDK takes from the scope's transaction name. Falls back to window.location.pathname if the scope has none. |
browser.bfcache.not_restored includes:
| Attribute | Description |
|---|---|
browser.bfcache.reason | A reason the browser reported for not restoring the page (for example, unload-listener, websocket). |
browser.bfcache.frame | Where the reason originated: the top document or a child frame. |
sentry.segment.name | The route the navigation landed on. |
browser.bfcache.reload.duration includes sentry.segment.name only.
The browser defines the notRestoredReasons strings, and they can change between versions. Chrome also reports a privacy-masked masked reason alongside real ones for cross-origin frames. Treat the reason values as a moving target rather than a fixed enum, and group on them accordingly in dashboards.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").