What is recorded

PhoenixReplay.Recorder starts recording on the connected mount of every LiveView in a live session that lists it in on_mount:

live_session :default, on_mount: [PhoenixReplay.Recorder] do
  live "/checkout", CheckoutLive
end

A recording is a list of PhoenixReplay.Recording.Event structs, each with a millisecond offset from the start of the session:

TypeData
:mountAssigns when recording started
:paramshandle_params/3 params and URI
:eventhandle_event/3 name and params; target: {module, id} for events handled by a LiveComponent
:infohandle_info/2 message tag, never the message itself
:renderAssigns changed by a render
:componentLiveComponent assigns changed by an update or event
:component_destroyedA LiveComponent removed from the page
:telemetryA telemetry event captured by a collector
:logA log message, when log collection is on
:exitThe formatted reason of a LiveView that exited abnormally
:viewportThe browser's viewport changed: a resized window, a rotated phone, or a switch to dark mode
:pointerA batch of pointer moves, presses and scroll offsets, when :pointer is on
:stateClient state reported by the browser, form control values included

The recording also keeps the view module, URL, sanitized params and session, and the start time. Everything passes through the configured sanitizer first; see Privacy and Security.

Browser and journey

A recording can also say which browser it came from and where the user went. The server cannot see these alone, so they are sent by the browser, and recordings simply leave them out when it does not send them.

import { replayParams, replayMetadata } from "phoenix_replay"

const liveSocket = new LiveSocket("/live", Socket, {
  params: () => ({_csrf_token: csrfToken, ...replayParams()}),
  metadata: replayMetadata
})
socket "/live", Phoenix.LiveView.Socket,
  websocket: [connect_info: [:user_agent, session: @session_options]]

mix igniter.install phoenix_replay makes both changes for the setup Phoenix generates. With them, a recording's PhoenixReplay.Recording.Client holds:

  • the viewport — width, height and pixel ratio when the LiveView connected. The player renders the replay at that size, keeping its aspect ratio: Fit scales it down until the whole viewport fits the window, centring a phone on a neutral stage, and 100% shows it at true size in a scrolling box. When a phone turns, the player shows it turning, the way the screen's angle changed, unless the viewer prefers reduced motion.
  • the media settings — the color scheme, reduced motion, contrast, the kind of pointer and whether it hovers, as the page's CSS saw them, with the viewport. The replayed page takes them, so its prefers-color-scheme, prefers-reduced-motion, prefers-contrast, pointer and hover rules, and Tailwind's dark:, motion-reduce:, contrast-more:, pointer-coarse: and hover: classes, show what the user saw: a phone session replays without hover styles. Stylesheets from another origin, and script that calls matchMedia, still see the viewer's. The Visit tab lists them.
  • resizes — a resized window or a rotated phone is recorded as a :viewport event when it settles, a fifth of a second after it stops changing, as long as replayRecorder runs; see Pointer, touches and scrolling. The viewport also travels with each click and key press, which catches changes without replayRecorder. Your handle_event/3 receives the extra "_replay" param; recorded params leave it out.
  • the user agent — shown in the player as, for example, "Safari on iOS".
  • the tab — an id kept in the tab's sessionStorage. Navigating to another LiveView starts a new recording; the tab id ties them into one journey, and the player links the previous and next sessions of the tab.
  • the previous page — the URL of the LiveView that live-navigated here (client.navigated_from).

Visit context

Some context exists only on the HTTP requests of a visit, not on the LiveView socket: headers such as Accept-Language, the external Referer a visitor arrived from, and the campaign params of the page they landed on, which later LiveViews no longer see. PhoenixReplay.Plug keeps what the :client config asks for in the session, and every recording of the visit carries it:

config :phoenix_replay,
  client: [
    headers: ["accept-language", "cf-ipcountry"],
    landing: [params: [:utm, :click_ids, "ref"], referrer: true]
  ]
pipeline :browser do
  # after :fetch_session
  plug PhoenixReplay.Plug
end
  • headers — an allowlist, refreshed on each request, each value cut to 256 characters. cookie, authorization and proxy-authorization are refused.
  • landing — the visit's first GET: its path, time, tracked query params and Referer. :utm and :click_ids expand to the usual parameter names. The referrer loses its query string unless referrer: :full, since query strings often carry tokens.
  • Attribution is first-touch: the landing is kept for the whole visit. attribution: :last replaces it whenever a request carries tracked params, to see which campaign brought someone back.

A visit lasts as long as the session cookie. The plug rewrites the session only when the kept context changes, and does nothing until :client asks for headers or a landing; the installer adds it to the :browser pipeline. The player shows the campaign, the referrer's host and the landing page, with the params and headers under "Visit details".

Headers such as x-forwarded-for or cf-connecting-ip hold IP addresses, which are personal data in many jurisdictions; capture them only when you need them. Captured headers and the landing go through the redactor when a recording is saved.

The client module is deps/phoenix_replay/priv/static/phoenix_replay.js, with types; bundlers that resolve packages from deps, as Phoenix's esbuild and Volt setups do, import it as "phoenix_replay".

Themes

A theme the user chooses in your app, rather than in their system, belongs on the server, like any setting, so recordings carry it: keep it in the session, give your LiveViews an @theme assign in an on_mount hook, and render it in your root layout, such as <html data-theme={@theme}>. A theme kept only in localStorage never reaches the server, so the replay cannot show it.

The replay needs nothing more. When the dashboard's :frame_layout is your root layout, the replay renders it again with each moment's assigns and gives the replayed page's <html> and <body> the attributes it renders then, as your layout would have live. The example app's ExampleWeb.Theme keeps a light, dark or system theme this way. A theme that follows the system is replayed from the recorded color scheme.

Older recordings

Replay renders today's templates with the assigns recorded then. So each recording keeps which code it was made with: the release, the MD5 of its view and LiveComponents, and the versions of the dependencies that render, such as LiveView and component libraries. When any of them differs from the running code, the player notes "Code changed" and names what changed, and its Visit tab shows the release. Name your releases after your deploys, so the list's Release filter finds the sessions of one:

# config/runtime.exs
config :phoenix_replay, release: System.get_env("GIT_SHA")

An assign a recording lacks needs nothing: it renders as nil, and the player notes it; see Limitations. An assign that changed shape since, such as a :dark_mode boolean that became a :theme, takes a migration, as a database's rows do: a module with a timestamp version, found among your app's modules with nothing to configure.

defmodule MyAppWeb.ReplayMigrations.DarkModeToTheme do
  use PhoenixReplay.Migration, version: 20261007120000

  @impl true
  def up(MyAppWeb.TaskLive.Index, %{dark_mode: dark?} = assigns),
    do: Map.put_new(assigns, :theme, if(dark?, do: "dark", else: "light"))

  def up(_view_or_component, assigns), do: assigns
end

Each recording keeps the newest version it was made with, and replay applies the newer migrations, in order, to its view's and LiveComponents' assigns; the Visit tab lists them. See PhoenixReplay.Migration.

For a root layout whose <html> attributes come from something other than its assigns, a PhoenixReplay.Replay module, configured as :replay, gives them. How one LiveView renders in a replay is PhoenixReplay.Replay.View's replay_render/1, below.

Pointer, touches and scrolling

PhoenixReplay can also record where the pointer moved, what it pressed and how the page scrolled, and the player shows them over the replay. It is off by default. Turn it on globally or per live session:

config :phoenix_replay, pointer: true

live_session :checkout, on_mount: [{PhoenixReplay.Recorder, pointer: true}] do
  # ...
end

and call replayRecorder from your JavaScript, after connecting the socket; mix igniter.install phoenix_replay adds it:

import { replayParams, replayMetadata, replayRecorder } from "phoenix_replay"

liveSocket.connect()
replayRecorder(liveSocket)

replayRecorder records nothing until a recorded LiveView mounts and says what to record, and stops when the page navigates to another LiveView. It also records client state. The browser samples the pointer and the scroll offset, and sends them in batches over the LiveView socket as an event the recorder takes before your view sees it. Each setting has a default:

config :phoenix_replay,
  pointer: [
    sample: 50,        # ms between recorded positions of a pointer
    scroll: 100,       # ms between recorded scroll offsets
    flush: 1_000,      # ms between the batches the browser sends
    max_points: 500,   # entries a batch holds before it is sent early
    limit: 3_600       # batches recorded per session
  ]

At the defaults, a moving pointer costs about 20 samples a second, a few hundred bytes, and a still one nothing. Mouse, pen and touch are recorded alike, each finger on its own and through scrolls and pinches, which the browser handles itself, and presses note the nearest element with an id, so the player can place them on it even if the replayed page lays out a little differently. Batches come from the browser, so the server drops anything malformed and caps each one at :max_points. They do not count towards :max_events, and pointer movement alone does not make a session interactive.

The fingers of a pinch are replayed, but not the zoom it causes: the page's pinch-zoom level is not recorded.

The player's clock runs to the end of the pointer track and of any client state, not only to the last LiveView event, so movement after the last event still plays.

Client state

Replay re-renders your view with its recorded assigns, so on its own it cannot show what lives only in the browser. PhoenixReplay covers that in three tiers, from no code to a little:

  1. Form controls, automatically. What users type and choose is recorded and put back into the replay, with no app code.
  2. Your own client state, with one function. State your JavaScript holds, such as a draft or a client-side selection, is one replayState call.
  3. Libraries and JavaScript-driven effects. A library reports with a DOM event, needing no dependency on PhoenixReplay, and a view renders what the browser did with replay_render/1.

All of it is recorded by default whenever replayRecorder runs; state: false turns it off, globally or per live session.

Form controls

Text typed into inputs and textareas, checkboxes and radios, and options chosen in selects are recorded as users change them, whether or not the form has a phx-change, and the replay puts them back into the page after each render. A handler that validates without storing the value in assigns no longer replays as an empty box. Each control waits for a pause, :debounce milliseconds, so a typed sentence is one step on the player's timeline, not one per key.

Some controls are never read in the browser at all, so their values never leave it:

  • password inputs, including one a "show password" toggle turned into text,
  • hidden inputs, file inputs and buttons,
  • fields whose autocomplete names a card (cc-…), a password (current-password, new-password) or a one-time code (one-time-code),
  • anything inside an element with a data-phx-replay-ignore attribute:
<div data-phx-replay-ignore>
  <.input field={@form[:ssn]} label="Social security number" />
</div>

The rest are recorded under their name, so your PhoenixReplay.Sanitizer filters names such as token or api_key the way it filters event params. state: [inputs: false] turns form controls off and keeps the rest of client state.

The replay finds each control again by its id, or by its form's id and its own name; a checkbox also by its value, as checkboxes often share a name. A control with neither an id nor a form id and name is not recorded. Controls that a component renders under a changing id are not found again either.

The replay shows values, not what your JavaScript did with them. If a script filters a list as the user types into a search box, the replay puts the query back into the box, but the list still shows every row, which looks like a wrong replay. Render that effect yourself with replay_render/1; see Rendering what the browser did.

Your own client state

State your JavaScript holds is one call. replayState merges its fields into what was reported under the key before, so report only what changed:

import { replayState } from "phoenix_replay"

replayState("draft", { body: editor.getText() })

Report whenever the state changes, without checking whether the page is recorded: PhoenixReplay keeps the latest state of each key, and a recording starts with the state as it is. State reported on one LiveView is forgotten when the page navigates to another.

For library authors

A library that cannot import PhoenixReplay reports the same way with a DOM event on window, so it needs no dependency on it, in Elixir or in JavaScript:

window.dispatchEvent(
  new CustomEvent("phx_replay:state", {
    detail: { key: "search", changes: { query: "shoes" } }
  })
)

key is a non-empty string naming the state, such as a component's id. changes is a JSON object of fields to merge into what was reported under key before, a shallow delta. It is copied when reported. Reports that are not a key and a JSON object within the limits are dropped. As with replayState, there is no need to know when recording starts.

A library that wants to know anyway can: replayRecorder dispatches phx_replay:start on window when the page's LiveView is recorded, with {state: settings | null} as its detail, and phx_replay:stop when recording ends, and <html> carries a data-phx-replay attribute holding the same detail as JSON while recording.

Rendering what the browser did

The replay merges the state recorded up to the current moment into a reserved assign, @phoenix_replay_state: a map of each key to its merged fields, string keys throughout, empty before any report. A view whose live render depends on code in the browser defines replay_render/1, the optional callback of PhoenixReplay.Replay.View, which the replay calls instead of render/1 with the same assigns plus that one:

@behaviour PhoenixReplay.Replay.View

@impl PhoenixReplay.Replay.View
def replay_render(assigns) do
  query = get_in(assigns.phoenix_replay_state, ["search", "query"])

  assigns
  |> assign(:visible, Enum.filter(assigns.tasks, &(query in [nil, ""] or &1.title =~ query)))
  |> render_list()
end

It is rendered in full on every step, so values you derive in it with assign/3 always show; @ access in ~H works as usual. Each report is a step on the player's timeline, in a lane of its own, so seeking to a moment shows the state as it was then. Form control values are under the "phx_replay:inputs" key, %{selector => %{name => value}}. Don't name an assign of your own :phoenix_replay_state.

Limits

config :phoenix_replay,
  state: [
    inputs: true,            # record form controls
    debounce: 300,           # ms a control must stay unchanged before it is recorded
    flush: 1_000,            # ms between the batches the browser sends
    max_entries: 200,        # entries a batch holds before it is sent early
    max_key: 64,             # bytes a key may have
    max_entry_bytes: 8_192,  # JSON size of one entry's changes; larger ones are dropped
    max_bytes: 65_536,       # JSON size a batch holds before it is sent early
    limit: 3_600             # batches recorded per session
  ]

Client state goes through your PhoenixReplay.Sanitizer's sanitize_params/1 when it arrives and through your PhoenixReplay.Redactor when the session is saved. It does not count towards :max_events. A changed form control makes a session interactive, as does a change to a key reported before; the first report of any other key, the state the page started with, does not.

PhoenixReplay does not record focus, or Phoenix.LiveView.JS commands applied on the client, which the replay does not re-run.

Which sessions are kept

Recording starts on every connected mount, but a session is saved only if the user interacted with it: it handled an event, in the view or a component, or navigated within the LiveView. Plain page views are discarded when the process exits.

:keep decides further, when the session ends. keep: [rate: 0.1] saves a tenth of interactive sessions, and errors: true or slower_than: ms always save sessions that hit an error or a slow query, even without interaction. See Keeping the sessions that matter.

Sampling and limits

Record a share of sessions with :sample_rate, from 0.0 to 1.0, and cap the events per session with :max_events. :sample_rate decides on mount; to decide once you know how the session went, record every session and use :keep instead. Set them globally:

config :phoenix_replay,
  sample_rate: 0.25,
  max_events: 10_000

or per live session, which overrides the global values:

live_session :checkout,
  on_mount: [{PhoenixReplay.Recorder, sample_rate: 1.0, max_events: 2_000}] do
  live "/checkout", CheckoutLive
end

Per-session options accept :sample_rate, :keep, :max_events, :sanitizer and :redact. Once a session reaches :max_events, further LiveView events are dropped and the recording is kept as it is. Collected telemetry and logs have their own limits.

:max_memory caps the buffer of sessions in progress, in bytes. While it is exceeded, new sessions are not recorded.

Telemetry

PhoenixReplay.Telemetry emits an event when a session is finalized:

  • [:phoenix_replay, :recording, :persisted] with event_count and duration_ms measurements,
  • [:phoenix_replay, :recording, :discarded] with a reason of :not_interactive or :not_sampled,
  • [:phoenix_replay, :recording, :failed] when saving gave up.

Each event fires after the session has left the buffer, so handlers see the finished state. [:phoenix_replay, :collector, :exception] reports a collector that raised; see Telemetry and Logs.

Limitations

Replay reconstructs the assigns of LiveViews and LiveComponents. It does not reconstruct:

  • streams and uploads, whose contents are not kept in assigns,
  • what your JavaScript did with client state, such as rows a script filtered, unless the view renders it with replay_render/1; see Client state,
  • focus, and Phoenix.LiveView.JS commands applied on the client.

Replay renders today's templates with the assigns recorded then. When a template reads an assign a recording lacks, such as one added after the session was recorded, the replay renders it as nil, which most templates take as unset, and the player notes "Not in recording: @name". A template that cannot take nil there still shows a placeholder for that moment.

Recordings name modules as atoms: the view, its LiveComponents, and structs in assigns. They are read back only with atoms the node knows, so a recording that names a module deleted or renamed since can no longer be read; rename a LiveView or LiveComponent only once its recordings no longer matter. Which code each recording was made with is kept by name, so that much stays readable.