Skip to content
You are reading the docs for Backstory 0.2 (private beta). Behavior may change before general availability; the changelog lists every change.

State bridges and OpenTelemetry

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);
StoreHow it is attached
ReduxattachRedux(store) subscribes without middleware, or install backstoryMiddleware() to preserve action names.
ZustandattachZustand(useStore) subscribes to one store. Call it once per store.
Piniapinia.use(Backstory.state.piniaPlugin()) attaches each Pinia store.
NgRxattachNgrx(store$, actions$) observes the store and optional action stream.
MobXattachMobx({ name, getSnapshot, reaction }) uses your MobX reaction.
TanStack QueryattachQueryClient(queryClient) captures query keys and status; data requires { includeData: true }.
ApolloattachApollo(client) captures cache keys; entities require { includeEntities: true }.
React component treeattachReactDevtoolsHook() captures component names and prop keys when the React DevTools hook is available.
Any storecaptureStore({ 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.

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.

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
},
});
OptionDefaultWhat it does
enabledtrueAdds trace headers to requests. Set false to turn linking off.
propagateSameOrigintrueAdds 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.
exportSpansfalse (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.id or 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.