---
title: "BFCache Metrics"
description: "Track browser back/forward cache (bfcache) health as Sentry Application Metrics."
url: https://docs.sentry.io/platforms/javascript/guides/effect/configuration/integrations/bfcache/
---

# BFCache Metrics | Sentry for Effect

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)](https://web.dev/articles/bfcache) and emits it as [Sentry Application Metrics](https://docs.sentry.io/product/metrics.md). 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?

```javascript
Sentry.init({
  integrations: [Sentry.bfcacheMetricsIntegration()],
});
```

This integration requires [Sentry Application Metrics](https://docs.sentry.io/platforms/javascript/guides/effect/metrics.md) 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`](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceNavigationTiming/notRestoredReasons) the browser reports for it. This API is currently Chromium-only, so the SDK records misses on other browsers without reasons.

## [Options](https://docs.sentry.io/platforms/javascript/guides/effect/configuration/integrations/bfcache.md#options)

### [`maxReasons`](https://docs.sentry.io/platforms/javascript/guides/effect/configuration/integrations/bfcache.md#maxreasons)

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:

```javascript
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`.

## [Emitted Metrics](https://docs.sentry.io/platforms/javascript/guides/effect/configuration/integrations/bfcache.md#emitted-metrics)

| 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. |

### [Attributes](https://docs.sentry.io/platforms/javascript/guides/effect/configuration/integrations/bfcache.md#attributes)

`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.

## [A Note on Reasons](https://docs.sentry.io/platforms/javascript/guides/effect/configuration/integrations/bfcache.md#a-note-on-reasons)

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.