State bridges and OpenTelemetry
State bridges
Section titled “State bridges”State bridges feed the Player’s State panel with actions and diffs so you can
time-travel from an action to the replay moment. State capture is opt-in:
Backstory.init({ state: … }) configures privacy and size limits, but it cannot
discover your application’s store. Attach the appropriate bridge after init.
Backstory.init({ projectKey: "pk_live_…", state: { denyPaths: ["/auth/token", "/user/ssn"], maxDiffBytes: 8192, snapshotEverySec: 60, },});
// Choose the bridges your app uses. Each call returns a detach function.const detachRedux = Backstory.state.attachRedux(store);const detachCart = Backstory.state.attachZustand(useCartStore);const detachQueries = Backstory.state.attachQueryClient(queryClient);const detachApollo = Backstory.state.attachApollo(apolloClient);| Store | How it is attached |
|---|---|
| Redux | attachRedux(store) subscribes without middleware, or install backstoryMiddleware() to preserve action names. |
| Zustand | attachZustand(useStore) subscribes to one store. Call it once per store. |
| Pinia | pinia.use(Backstory.state.piniaPlugin()) attaches each Pinia store. |
| NgRx | attachNgrx(store$, actions$) observes the store and optional action stream. |
| MobX | attachMobx({ name, getSnapshot, reaction }) uses your MobX reaction. |
| TanStack Query | attachQueryClient(queryClient) captures query keys and status; data requires { includeData: true }. |
| Apollo | attachApollo(client) captures cache keys; entities require { includeEntities: true }. |
| React component tree | attachReactDevtoolsHook() captures component names and prop keys when the React DevTools hook is available. |
| Any store | captureStore({ store: "custom", storeName, getState, subscribe }). |
The bridge emits a masked, size-capped snapshot immediately and every
snapshotEverySec, with RFC 6902 diffs between snapshots. All values pass
through the same PII detectors as text. Keys such as password, token, ssn,
and card are redacted by name.
Application collector
Section titled “Application collector”Storage keys (not values), cookie names (not values), service worker state, and feature flags from LaunchDarkly, Statsig, Split, and Unleash are captured into the Application panel. Values are captured only for keys you allowlist.
OpenTelemetry
Section titled “OpenTelemetry”Replays link to backend traces by default. Every same-origin request gets a traceparent header and a baggage header carrying session.id, and the recorder stores the trace id with the request. Nothing extra is uploaded from the browser for this.
The SDK contains a 3 KB OTLP/JSON emitter. It does not bundle the OpenTelemetry web SDK. If your page already runs the OpenTelemetry web SDK, Backstory attaches its attributes to your spans instead of creating its own.
Backstory.init({ projectKey: "pk_live_…", otel: { propagateTraceContext: ["https://api.example.com"], // also inject traceparent into these origins exportSpans: true, // upload page load, click, and request spans },});| Option | Default | What it does |
|---|---|---|
enabled | true | Adds trace headers to requests. Set false to turn linking off. |
propagateSameOrigin | true | Adds trace headers to requests to the page’s own origin. |
propagateTraceContext | [] | Other origins (globs) that get trace headers. Only list origins whose CORS policy allows traceparent and baggage. |
exportSpans | false (true when you set enabled: true yourself) | Uploads browser spans so traces start at the click. |
serviceName | "browser" | Service name on browser spans. |
What you get:
- In the Player, the Network panel shows the backend span tree under each request once your backend sends traces to Backstory.
- The Console panel’s Server tab lists backend log lines and backend errors from the same requests, in time order with the replay.
- Spans and logs join the session by
session.idor by the trace id the browser sent, so services deeper in the call chain link even when they never see the session id.
To send backend data, install a Backstory backend SDK or point any OpenTelemetry exporter at POST /v1/otlp/traces, /v1/otlp/logs, or /v1/otlp/metrics with a server key (Authorization: Bearer sk_live_…). Create server keys under Backend → Connect a service (or Backend → Settings → Server keys). The browser project key can only send browser spans.