Application

Storage

config :phoenix_replay,
  storage: {PhoenixReplay.Storage.File, path: "priv/replay_recordings"}

A {module, opts} tuple or a bare module. Default: files under priv/replay_recordings.

Ecto storage

config :phoenix_replay,
  storage: {PhoenixReplay.Storage.Ecto, repo: MyApp.Repo}

Sanitizer

config :phoenix_replay, sanitizer: MyApp.ReplaySanitizer

Default: PhoenixReplay.Sanitizer.Default.

Sampling

config :phoenix_replay, sample_rate: 0.25

Share of sessions recorded, 0.0 to 1.0. Default: 1.0.

Event limit

config :phoenix_replay, max_events: 10_000

LiveView events kept per session. Default: 10_000.

Tail sampling

config :phoenix_replay,
  keep: [rate: 0.05, errors: true, slower_than: 1_000],
  max_memory: 256 * 1024 * 1024

Decides when a session ends whether it is saved; marks: true also keeps every session with a mark. Default: rate: 1.0, no error, slowness or mark rules, no memory limit.

Telemetry

config :phoenix_replay,
  collect: [
    {PhoenixReplay.Collector.Ecto, repo: MyApp.Repo, slower_than: 5},
    PhoenixReplay.Collector.Finch,
    {[:my_app, :checkout, :stop], metadata: [:order_id], limit: 100}
  ]

Default: []. Each collector keeps 1_000 events per session unless :limit is set.

Logs

config :phoenix_replay, logs: [level: :info, metadata: [:request_id]]

Off by default.

Redaction

config :phoenix_replay, redact: [~r/\b\d{13,19}\b/]

Masks matches in every recorded string when a session is saved.

Obscura

config :phoenix_replay, redact: {PhoenixReplay.Redactor.Obscura, []}

Detects personal data. Needs {:obscura, "~> 0.2"}.

Writing running sessions

config :phoenix_replay, flush: [events: 200, interval: 5_000]

Writes kept sessions to storage in chunks while they run. flush: false saves them only when they end.

Pointer, touches and scrolling

config :phoenix_replay,
  pointer: [sample: 50, scroll: 100, flush: 1_000, max_points: 500, limit: 3_600]

Off by default; pointer: true uses these defaults. Needs replayRecorder(liveSocket) in the browser. See Recording.

Client state

config :phoenix_replay,
  state: [
    inputs: true,
    debounce: 300,
    flush: 1_000,
    max_entries: 200,
    max_key: 64,
    max_entry_bytes: 8_192,
    max_bytes: 65_536,
    limit: 3_600
  ]

On by default; state: false records none, and inputs: false records everything but form controls. Needs replayRecorder(liveSocket) in the browser. See Recording.

Releases

config :phoenix_replay, release: System.get_env("GIT_SHA")

The deploy each session is recorded on, shown in the player and filterable in the list; defaults to your app's version. See Recording.

How recordings replay

config :phoenix_replay, replay: MyAppWeb.Replay

A PhoenixReplay.Replay module giving the replayed page's <html> attributes your layout takes from something other than its assigns. Optional: your root layout's attributes follow the replayed assigns by themselves, an assign a recording lacks renders as nil, and assigns that changed shape take a PhoenixReplay.Migration, found without configuration. See Recording.

Video export

config :phoenix_replay,
  export: [
    endpoint: MyAppWeb.Endpoint,
    fps: 30,
    max_dpr: 2,
    idle: 3_000,
    hold: 1_000,
    crf: 23,
    preset: "veryfast",
    max_concurrency: 1,
    ttl: :timer.hours(1),
    playwright: [executable: "node_modules/.bin/playwright"]
  ]

Off by default. Needs {:playwright_ex, "~> 0.14"} and {:muontrap, "~> 1.6"}, with Playwright's Chromium and ffmpeg. See Exporting videos.

Retention

config :phoenix_replay,
  retention: [max_age: :timer.hours(24 * 7), max_count: 1_000, interval: :timer.minutes(10)]

Off unless :max_age or :max_count is set. Default interval: one minute.

Save retries

config :phoenix_replay, persist: [attempts: 3, backoff: 1_000]

Backoff in milliseconds, multiplied by the attempt number.

Install and testing

Install

mix igniter.install phoenix_replay

Recording off in tests

# config/test.exs
config :phoenix_replay, sample_rate: 0.0

Browser context

LiveSocket

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

const liveSocket = new LiveSocket("/live", Socket, {
  params: () => ({_csrf_token: csrfToken, ...replayParams()}),
  metadata: replayMetadata
})

liveSocket.connect()
replayRecorder(liveSocket)

Viewport, media settings and tab for each recording; replayRecorder adds form input, client state, resizes and, with pointer: true, the pointer.

User agent

socket "/live", Phoenix.LiveView.Socket,
  websocket: [connect_info: [:user_agent, session: @session_options]]

Visit context

config :phoenix_replay,
  client: [
    headers: ["accept-language"],
    landing: [params: [:utm, :click_ids]],
    media: [:color_scheme, :reduced_motion, :contrast, :pointer, :hover]
  ]

Headers and the landing need plug PhoenixReplay.Plug in the :browser pipeline. First-touch by default; attribution: :last follows the latest campaign. media lists the browser's media settings to keep, all by default, false for none. :context is this option's former name.

Live sessions

Record a live session

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

Per-session options

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

Accepts :sample_rate, :keep, :max_events, :sanitizer and :redact.

Router

Mount the dashboard

import PhoenixReplay.Router

scope "/admin" do
  pipe_through [:browser, :require_admin]
  phoenix_replay "/replay"
end

Authentication and authorization

phoenix_replay "/replay",
  on_mount: [{MyAppWeb.UserAuth, :ensure_admin}],
  authorize: MyApp.ReplayAuthorization

Frame layout

phoenix_replay "/replay", frame_layout: {MyAppWeb.Layouts, :root}

For content-hashed assets. Default: loads /assets/css/app.css.

Socket path

phoenix_replay "/replay", live_socket_path: "/socket/live"

Default: "/live".

Mount twice

phoenix_replay "/replay", as: :staff_replay

Dashboard filters

Parameters

ParameterMatches
qText in URL, id, event or mark names, source or campaign
viewView module name
eventTriggered event name
markA mark the session reached
source, medium, campaignWhere the visit came from
device_typephone, tablet or desktop
browserBrowser family, such as Mobile Safari
releaseThe release it was recorded on
within15m, 1h, 24h, 7d or 30d
from, toStart time range, ISO 8601 in UTC
longer_thanMinimum duration in seconds
min_eventsMinimum event count
errors1 for sessions with an error
tabOne browser tab's sessions

In code

PhoenixReplay.Trace.find(event: "pay", within: "24h", errors: true)

Takes the same filters as keywords. See PhoenixReplay.Trace.