Session Replay

A session replay is a recording of what a real user did in the product: the clicks, the navigation, the dead-ends. It is the fastest way to understand a bug report or a confusing flow, because you watch it happen instead of guessing from a stack trace.

We usually run session replay on OpenReplay. Early-stage products already on PostHog, this one included, use PostHog’s built-in replay instead, so the setup shown below is PostHog. The discipline is the same on either tool.

Reproduce from the real path. See the exact sequence that led to the bug, not your best guess at it.
Find the friction. Rage clicks, back-and-forth, and abandonment show you where a flow confuses people.
Ground Discover in reality. What people actually do beats what they say they do.

Replays are captured only on deployed environments, never on localhost, so local development is never recorded.

Privacy first

This part is not optional. A replay can capture whatever is on screen, so we mask by default and record nothing sensitive.

All input values are masked (maskAllInputs). We never see what someone typed into a field.
Sensitive content on screen gets data-mask. Tag the element and its text is blanked in the recording.

<span data-mask>{patient.fullName}</span>

Never record names, health data, tokens, or payment details in the clear. When in doubt, mask it. Masking too much costs you a slightly less useful replay; masking too little is a data leak. The trade is not close.

How it is set up

Configured once in initPostHog (apps/web/src/lib/posthog.ts), called at app start. You do not wire recording up per page:

posthog.init(apiKey, {
  disable_session_recording: !isDeployed, // off on localhost
  session_recording: {
    maskAllInputs: true,
    maskTextSelector: "[data-mask]",
  },
});

Recording runs for deployed sessions and respects the masks above. As a feature author your job is to tag each new sensitive surface with data-mask as you build it, so nothing sensitive is ever captured in the first place.

Using a replay

Open the replay tool (OpenReplay, or PostHog on this product), find the session (by user, by error, or by the flag that was on), and watch. Pair the replay with the error and the trace to see the exact path in. The replay shows you what happened; the trace and the code tell you why. Feed what you learn back into the fix and its regression test.