0.6.2 - 2026-10-09
Two replay fixes: a view's own layout, and lists of integers.
Fixed
- A LiveView replays inside its own layout, with its navigation and flash messages: the one its
use Phoenix.LiveView, layout: ...names, or onemount/3or anon_mounthook returned withlayout:. Recordings keep which layout the view rendered in. - Lists of small integers, such as
%{"ids" => [11]}, show as numbers in the player andmix phoenix_replay.show, not as charlists like~c"\v".
0.6.1 - 2026-10-08
Documentation brought up to date with 0.6.
Fixed
- The README and guides show
replayRecorderin the browser setup, and no longer say that nothing changes in your JavaScript. - The configuration cheatsheet lists every recording list filter, and its code example uses
PhoenixReplay.Trace.find/1. - How It Works describes how events, the root layout, migrations and missing assigns are recorded and replayed in 0.6.
0.6.0 - 2026-10-08
Pointer, touch and form recording, marks, video export, and a richer player and recording list.
Upgrading
- Ecto storage: run migration version 3,
PhoenixReplay.Storage.Ecto.Migration.up(from: 2, version: 3). Saving and listing fail until it runs. - Renamed modules:
PhoenixReplay.Recordingsis nowPhoenixReplay.Catalog,Recordings.FilterisPhoenixReplay.Recording.Filter,Recordings.RetentionisPhoenixReplay.Storage.Retention,Recording.KeepisPhoenixReplay.Session.TailSampling, andRecordings.complete/3isPhoenixReplay.Session.Finalizer.complete/3. PhoenixReplay.Recording.Summary'ssourceholds only the source, withmediumandcampaignbeside it. A recording'sclientis aPhoenixReplay.Recording.Clientstruct, whoserefereris nownavigated_from. Saved recordings are upgraded when read.- Custom storage backends: the optional
facets/1callback is replaced byvalues/4, andPhoenixReplay.Storage.File.query/3is gone. :flush,:pointer,:logsand:landingset on a live session now merge into the global configuration instead of replacing it.- The
:contextoption is now:client, as recordings call it.:contextstill works, with a deprecation warning.
Added
- Pointer, touch and scroll recording with
pointer: true. CallreplayRecorder(liveSocket)in your client code; the installer adds it. - Form inputs are recorded and replayed with no app code. Passwords, payment and one-time-code fields are never read;
state: [inputs: false]turns it off. - Client-only state: report it with
replayState(key, changes), and the replay renders it from@phoenix_replay_state, or with a view'sreplay_render/1, fromPhoenixReplay.Replay.View. - Marks: collect a telemetry event with
mark: trueto mark a moment such as a signup or a checkout. Marks get a timeline lane, a header menu and a list filter, andkeep: [marks: true]saves every session that reaches one. phx_replay:startandphx_replay:stopwindow events, and adata-phx-replayattribute on<html>, tell browser code when a page is recorded.- The player draws the recorded cursor, taps and touches over the replay, and scrolls the page as the user did.
- The player's View menu: Fit, Actual size, Rotate, and Follow scroll. Rotate turns the shown device to look at it the other way round; when the user turned their phone, the replay shows it turning.
- The recorder captures the user's color scheme, reduced motion, contrast, pointer type and hover with the viewport, and the replay applies them to the page's media rules, so a dark-mode or phone session looks as it did,
dark:andpointer-coarse:styles included, and a phone session shows no desktop scrollbar. The Visit tab lists them, andclient: [media: …]keeps fewer. - The replay renders your root layout again with each moment's assigns, so
<html>and<body>attributes that follow them, such as a theme the server keeps, change as the session plays. APhoenixReplay.Replaymodule, configured as:replay, covers layouts that read something else. See the recording guide's "Themes". - The State tab shows what each event changed, such as
tasks[id: 2].done: false → true. - A details pane for the playing or pinned event, with telemetry measurements. Slow queries and calls stand out.
- SQL, assigns and metadata are syntax-highlighted.
- Keyboard shortcuts in the player;
?lists them. - A light and dark theme switch.
- The recording list filters by source, medium and campaign, device, browser, duration and mark, as chips that show how many sessions have each value.
- A chart of sessions over time above the list, with errors in red; click a bar to narrow the list to it.
- List rows show the device, browser, where the visit came from and the marks it reached.
- A time window or a calendar date range for the list. Dashboard times are in the viewer's time zone.
- Video export: turn a recording into an MP4 from the player's menu or with
mix phoenix_replay.export <id>. Setexport: [endpoint: MyAppWeb.Endpoint]; it needsffmpegand the optionalplaywright_exandmuontrapdependencies. SeePhoenixReplay.Export. PhoenixReplay.Export.Queue.Obanruns exports in your Oban queue, so they survive restarts and deploys.- Replay migrations: a module with
use PhoenixReplay.Migration, version: …andup(view_or_component, assigns)adapts recordings whose assigns changed shape since. Each recording keeps the newest version it was made with, and replay applies the newer ones, in order. See the recording guide's "Older recordings". - Each recording keeps which code it was made with: the release, set with
:releaseor your app's version, the MD5 of its view and LiveComponents, and the versions of the dependencies that render. The player notes "Code changed" when they differ from the running code, and the list filters by Release. PhoenixReplay.Trace,mix phoenix_replay.listandmix phoenix_replay.showread recordings as plain data, for IEx, tests and coding agents. Two agent skills ship in the package'sskillsdirectory.- Optional
child_spec/1andhistogram/4callbacks for storage backends.
Changed
- The default sanitizer also filters card numbers, CVVs, social security numbers, PINs and one-time codes.
- LiveView internals such as
:__changed__,:uploadsand:streamsare dropped from recorded assigns before your sanitizer sees them. - Resizes and rotations are recorded as soon as they settle, not with the next click.
- Menus and tooltips are no longer cut off by scrolling panels.
- Lumis is a new dependency, for syntax highlighting.
Fixed
- Scrubbing to the start no longer shows "Could not render".
- Scrubbing between events and pausing keep the moment you chose instead of jumping back to the previous event.
- Copy link links the exact moment the clock shows.
- Switching from 100% back to Fit after scrolling no longer shifts the page out of view.
- Collected details, such as SQL, no longer break words mid-way.
- A recording made before a template began to read an assign replays with it unset, and the player notes which, rather than showing "Could not render".
- An event that one of your
on_mounthooks handles and halts is recorded too, wherever the hook sits: events are recorded from LiveView's telemetry. - On a wide screen the player fits the window, so the page no longer scrolls; the replay scales to the space left.
- The Visit tab shows landing parameters beside their names, not on a line below.
- Running
iex -S mixor a Mix task next to a running server no longer marks the server's sessions as interrupted. - A save that fails, such as while the database is down, is retried instead of losing the recording.
- A LiveComponent that fails to record is reported through
[:phoenix_replay, :collector, :exception]telemetry instead of a log line.
0.5.1 - 2026-10-04
The rest of the dashboard redesign.
Added
- The player's kind filters have an Errors chip that narrows the event list to the events that report an error, under the interaction that caused them.
/focuses the search on the recording list and in the player.- On phones, the recording list has All, With errors and Last 24 h quick filters under the search.
- The replay is labelled "Replayed from recorded assigns", since it re-renders the view rather than capturing the screen.
Changed
- Text search in the recording list also matches event names.
PhoenixReplay.Storage.Ectochecks it after the SQL criteria, as it does for the event filter, since event names are stored encoded; it no longer uses an SQL fragment. - Errors on the timeline are larger, with a soft ring.
0.5.0 - 2026-10-04
Added
- Telemetry collection.
:collectlistsPhoenixReplay.Collectors, whose events are recorded in the session of the process that emitted them, or of the LiveView that started it as a task, and listed in the player under the event that caused them.PhoenixReplay.Collector.Ectorecords queries,PhoenixReplay.Collector.Finchrecords HTTP requests made with Finch or Req, and any event name records that event throughPhoenixReplay.Collector.Generic. - Log collection with
:logs, which records Logger messages in the same way. - Tail sampling with
:keep:ratesaves a share of sessions when they end, anderrors: trueandslower_than: msalways save sessions with an error or a slow collected event. LiveViews that exit abnormally record an:exitevent. :max_memorystops recording new sessions while the buffer is larger.- Running sessions are written to storage in chunks, as
:flushconfigures (by default every 200 events or 5 seconds), once:keepdecides to keep them. Their events leave memory, a crash of the node loses at most the last chunk, and the next start saves what was written as an interrupted recording, emitting[:phoenix_replay, :recording, :recovered].PhoenixReplay.Storage.Fileimplements the new optionalappend/3,fetch_partial/2andpartials/1callbacks, and takessync: trueto sync each chunk. - File storage writes recordings and summaries to a temporary file, syncs and renames them into place.
- The application waits for recordings being saved or written when it stops.
:redacttakes aPhoenixReplay.Redactor, which masks sensitive values in every recorded string when a session is saved, in a background task, and when the dashboard opens a running session. A list of regexes usesPhoenixReplay.Redactor.Patterns;PhoenixReplay.Redactor.Obscuradetects personal data with the optional Obscura dependency. A failing redactor stops the save rather than storing unredacted data.- The player redacts running sessions with
start_async/3and shows progress, and hands the result to its frame. [:phoenix_replay, :collector, :exception]reports collectors that raised.PhoenixReplay.Recording.Summarycountserror_count, the dashboard marks errors and filters sessions with?errors=1, and the player hides events by kind.on_mount: {PhoenixReplay.Recorder, opts}accepts:keepand:redact.- Recordings can carry the browser's viewport, user agent, tab and the URL the user came from, sent by the new client module (
import { replayParams, replayMetadata } from "phoenix_replay") and:user_agentin the LiveView socket'sconnect_info. Resizes are recorded as:viewportevents. The player renders the replay at the recorded viewport, keeping its aspect ratio — fitted to the window or at 100% in a scrolling box — names the browser, and links the sessions of one tab; the dashboard filters them with?tab=. The installer wires up the client and the user agent. PhoenixReplay.Plugand the:contextoption keep request context for a visit in the session, so every recording carries it: an allowlist of:headers, and the:landingrequest with its path, campaign params (:utmand:click_idspresets) and referrer, first-touch or last-touch. The player shows the campaign, referrer and landing page. The installer adds the plug to the:browserpipeline.PhoenixReplay.Recordings.fetch/3redacts running sessions and reports progress;PhoenixReplay.Recordings.live?/1tells running sessions apart.- The dashboard follows the system's dark mode, or
data-theme="light"/"dark"on its<html>. It ships the Geist and Geist Mono fonts and Lucide icons throughphoenix_iconify, so it needs nothing from the host app. - The player follows the redesign: a header with the recording's page, time, a jump to its first error and a link to the current moment (
?at=<index>opens the player there), the replay under a URL bar, playback controls with a timeline lane per kind of event, and a side panel. Its Events tab groups events by interaction, filters them by text and kind, and opens a query's, log's or exit's details under it; State shows the assigns at that moment, marking the ones it set; Visit shows the device, browser tab, referrer and landing. PhoenixReplay.Recording.Summarycarries the session'sviewport,device(such as "Mobile Safari 18 on iOS") andsource(the landing's campaign or referring host), and the recording list shows them. Devices are named withua_parser, a new dependency. On phones, the list's filters sit behind a Filters button.- The recording list keeps its place while sessions end: saved recordings are listed as of when the list was opened or its filter changed, and newer ones are counted in a "3 new recordings · Show" banner instead of shifting the rows.
- The recording list reads one page at a time through the new optional
PhoenixReplay.Storagecallbacksquery/3(filters, offset, limit,:sinceand:until, with a total) andfacets/1(views and event names to suggest).PhoenixReplay.Storage.Ectopages in SQL, andPhoenixReplay.Storage.Filekeeps summaries in an ETS index, reading only the summary files it has not seen. Backends without them are paged fromlist/1as before. - The recording list shows running sessions under "Live now" and saved ones in a table with relative start times, duration, events and errors. A whole row opens its recording, and it pages with numbered links.
Changed
Internal modules are grouped by role:
PhoenixReplay.Capture.*observes LiveViews,PhoenixReplay.Session.*follows a running recording until it is stored.PhoenixReplay.Recorderis only theon_mounthook.PhoenixReplay.Retentionis nowPhoenixReplay.Recordings.Retention; the:retentionoption is unchanged.[:phoenix_replay, :recording, :discarded]metadata carries areason::not_interactiveor:not_sampled.PhoenixReplay.Storage.Ectostoreserror_count,tab,viewport,device,sourceandsaved_at. The table now comes fromPhoenixReplay.Storage.Ecto.Migration, which needsecto_sql, now an optional dependency; upgrade one made by 0.4 with a new migration:def up, do: PhoenixReplay.Storage.Ecto.Migration.up(from: 1, version: 2) def down, do: PhoenixReplay.Storage.Ecto.Migration.down(from: 1, version: 2)
Fixed
- LiveComponent state applied by
start_async,assign_asyncandstream_asyncresults is recorded. LiveView emits no telemetry for it yet, soPhoenixReplay.Capture.AsyncResultssnapshots the component after such renders; see phoenix_live_view#4463. - LiveViews not mounted at the router, such as
live_render/3children, are recorded instead of crashing.
0.4.0 - 2026-10-03
Added
- LiveComponent state is recorded and replayed with no changes to components. Recording uses LiveView's component telemetry; replay renders each component's template with its recorded assigns. Events handled by components are recorded, so sessions with only component interaction are kept.
mix igniter.install phoenix_replaymounts the dashboard behind:dev_routes, turns recording off in tests, imports the formatter settings and ignores local recordings.:sample_raterecords a share of sessions.on_mount: {PhoenixReplay.Recorder, opts}sets:sample_rate,:max_eventsand:sanitizerper live session.- Dashboard filters by view, URL or id, triggered event, age and event count, kept in the URL.
PhoenixReplay.Recordings.Filterapplies the same criteria in code. PhoenixReplay.Recording.Summarylists the session's distinctevent_names. Recordings saved by 0.3.0 have none, so event filters do not match them.- Guides for getting started, recording, LiveComponents, the dashboard, storage, privacy and security, and testing, plus a configuration cheatsheet.
Changed
PhoenixReplay.Telemetryevents fire after the session has left the buffer, so handlers observe the finished state.
Fixed
- The recorder monitor no longer crashes on an unexpected
:DOWNmessage. - Stored structs decode with defaults for fields added after they were saved.
Upgrading
PhoenixReplay.Storage.Ectoneeds anevent_namescolumn:add :event_names, :binary, null: false, default: <<131, 106>>, the encoding of an empty list.- Add
config :phoenix_replay, sample_rate: 0.0toconfig/test.exsunless your tests should record sessions.
0.3.0
A rewrite for a cleaner architecture. Configuration, storage formats and public modules changed; recordings saved by 0.2 are not readable.
Breaking
- Configuration is validated by
PhoenixReplay.Config.:storagetakes{module, opts}and replaces:storage_opts; retention and persistence options moved under:retentionand:persist. PhoenixReplay.Store,PhoenixReplay.Persistenceand the oldPhoenixReplay.Recordingsare replaced byPhoenixReplay.Recordings,PhoenixReplay.Recorder.Buffer,PhoenixReplay.Recorder.Monitor,PhoenixReplay.Recorder.PersisterandPhoenixReplay.Retention.- Events are
PhoenixReplay.Recording.Eventstructs; listings returnPhoenixReplay.Recording.Summarystructs. - The
:authorizefunction config is replaced by thePhoenixReplay.Authorizationbehaviour, passed to the router macro. - Storage backends implement
save/2,fetch/2,list/1,delete/2andclear/1;init/1and the optional callbacks are gone. JSON storage and legacy file formats are removed. - Sanitizers implement
sanitize_assigns/1andsanitize_params/1;sanitize_delta/2is removed. Sensitive values are replaced with"[FILTERED]"instead of dropped. PhoenixReplay.Recorder.attach/3is removed; use theon_mounthook.- Requires Elixir 1.18 and Phoenix LiveView 1.1.
Fixes
- Deleting and clearing recordings respect authorization.
- Viewers of the same recording no longer drive each other's playback.
- Recordings that fail to save no longer leak buffered events.
- In-progress recordings survive worker restarts.
- One unreadable file no longer hides every recording.
- The replay frame catches template errors instead of crashing.
- Missing recordings respond with 404 under the dashboard path.
Improvements
- Dashboard ships its own CSS and a TypeScript player, and loads the host's own Phoenix and LiveView clients.
- Server-driven playback with a keyboard-accessible timeline.
- Recorded flash messages are replayed.
- Listing reads summaries without decoding recordings.
- Telemetry events for saved, discarded and failed recordings.
- The dashboard refreshes over PubSub instead of polling.
0.2.0
Improvements
- Extract replay player JavaScript into packaged static assets
- Add dashboard pagination, delete controls, and clear-all controls
- Add recording retention cleanup by count and age
- Retry async persistence failures before logging final failure
- Add Ecto storage integration coverage and GitHub Actions CI
- Auto-scroll events panel to keep the active event visible during playback
- Filter idle sessions (no user events) from the dashboard index
Store.list_active/0— list active recordings without private LiveView debug APIsRecorder.attach/3now accepts optionalparamsandsessionarguments
0.1.0 — 2026-03-10
- Initial release