Validated runtime configuration.
This is the only module that reads the :phoenix_replay application
environment. Everything else receives a t/0 explicitly, which keeps
configuration decisions at the boundary and lets tests pass their own.
Options
:storage—{module, opts}implementingPhoenixReplay.Storage. Defaults to{PhoenixReplay.Storage.File, []}.:sanitizer— module implementingPhoenixReplay.Sanitizer. Defaults toPhoenixReplay.Sanitizer.Default.:max_events— events recorded per session before recording stops. Defaults to10_000.:sample_rate— share of sessions to record, from0.0to1.0. Defaults to1.0, recording every session.0.0turns recording off.:keep— keyword list choosing which recorded sessions are saved when they end, as described in "Tail sampling" below::rate— share of interactive sessions to save (default1.0):errors— always save sessions with an error (defaultfalse):marks— always save sessions with a telemetry event collected withmark: true, such as a completed checkout (defaultfalse):slower_than— always save sessions with a collected event lasting at least this many milliseconds (defaultnil)
:collect— telemetry events to record alongside LiveView events. Each entry is aPhoenixReplay.Collectormodule,{module, opts}, an event name, or{event_name, opts}forPhoenixReplay.Collector.Generic. Every entry accepts:limit, the events recorded per session (default1_000). Defaults to[].:logs— keyword list enablingLoggercollection, ornil(the default) to leave logs out. SeePhoenixReplay.Capture.Logs.:redact— aPhoenixReplay.Redactorthat masks sensitive values when a recording is saved: a list of regexes, or regex sources as strings, forPhoenixReplay.Redactor.Patterns, or{module, opts}. Defaults to[], which stores recordings as the sanitizer left them.:flush— keyword list controlling how running sessions are written to storage in chunks, when the storage supports it (seePhoenixReplay.Storage), orfalseto save each session only when it ends::events— events buffered before a chunk is written (default200):interval— milliseconds after which buffered events are written anyway (default5_000)
:pointer— records the pointer, touches and scrolling, for the player to show over the replay, when the client module'sreplayRecorder/1runs in the browser.trueuses the defaults; a keyword list sets any of them;false(the default) records none::sample— milliseconds between recorded pointer positions (default50):scroll— milliseconds between recorded scroll positions (default100):flush— milliseconds between the batches the browser sends (default1_000):max_points— positions, presses and scrolls a batch may hold; a fuller batch is sent early, and the server drops the rest (default500):limit— batches recorded per session (default3_600, an hour of movement at the default:flush)
:state— records state that lives only in the browser, when the client module'sreplayRecorder/1runs: what is typed and chosen in form controls, and what app code reports withreplayState/2; seePhoenixReplay.Capture.State. On by default;falserecords none, and a keyword list sets any of::inputs— whether form controls are recorded (defaulttrue). Passwords, hidden inputs, card fields and one-time codes are never read; see "Client state" in the recording guide:debounce— milliseconds a form control must stay unchanged before its value is recorded, so typing a sentence is one entry (default300):flush— milliseconds between the batches the browser sends (default1_000):max_entries— entries a batch may hold; a fuller batch is sent early, and the server drops the rest (default200):max_key— bytes a key may have (default64):max_entry_bytes— the JSON size an entry's changes may have; larger ones are dropped (default8_192):max_bytes— the JSON size a batch may have; a fuller batch is sent early, and the server drops the rest (default65_536):limit— batches recorded per session (default3_600)
:client— what recordings keep inclientabout the browser and the visit.:contextis its former name, still read, with a warning::media— the media settings the browser reports with its viewport, which the replay applies to the page: a list of:color_scheme,:reduced_motion,:contrast,:pointerand:hover(default all of them), orfalsefor none. See "What the browser sends" in the privacy guide:headers— request header names to capture, refreshed on each request (default[]).cookie,authorizationandproxy-authorizationare refused.:landing— keyword list capturing the visit's landing request, ornil(the default)::params— query params to keep: names, or the presets:utm(utm_source,utm_medium,utm_campaign,utm_term,utm_content) and:click_ids(gclid,fbclid,msclkid):referrer—truekeeps theRefererwithout its query string,:fullkeeps all of it,falsenone (defaulttrue):attribution—:firstkeeps the first landing of the visit;:lastreplaces it whenever a request carries tracked params (default:first)
:release— the name of the running deploy, such as a commit from your host's environment, recorded with each session, shown in the player and filterable in the list;nil(the default) uses the version of the view's application. Only for people: nothing is decided by it; seePhoenixReplay.Recording.Code.:replay— aPhoenixReplay.Replaymodule adapting how recordings replay, such as the assigns older recordings hold, ornil(the default).:max_memory— bytes of buffered recordings above which new sessions are not recorded, ornil(the default) for no limit.:retention— keyword list controllingPhoenixReplay.Storage.Retention::max_age— milliseconds after which recordings are deleted:max_count— number of most recent recordings to keep:interval— milliseconds between pruning runs (default60_000)
:export— video export withPhoenixReplay.Export, off by default. A keyword list turns it on;:endpointis required::endpoint— your endpoint, which serves the stylesheets and scripts the replayed pages load:frame_layout—{module, function}root layout for exported replays, as the router's option of that name (default the dashboard's frame layout):dir— where finished videos are kept (defaultphoenix_replay/exportsin the system's temporary directory):ttl— milliseconds a finished video is kept (default3_600_000):max_concurrency— videos exported at once; more wait their turn (default1).PhoenixReplay.Export.Queue.Obantakes its limit from its Oban queue instead.:queue— where exports wait and run, aPhoenixReplay.Export.Queue: a module or{module, opts}(defaultPhoenixReplay.Export.Queue.Local):fps— frames per second (default30):max_dpr— the highest device pixel ratio to render at, which bounds the video's size (default2):idle— milliseconds a stretch without activity is shortened to, ornilto keep it whole (default3_000):hold— milliseconds the last moment is held at the end (default1_000):crf— the H.264 quality, lower is better (default23):preset— the x264 speed preset (default"veryfast"):ffmpeg— theffmpegexecutable (default"ffmpeg"):playwright— options forPlaywrightEx.Supervisor, such as:executableor:ws_endpoint(default[]):max_shots— the most screenshots an export may take, as files until the video is encoded; longer exports fail with a message to choose a shorter range (default3_600, two minutes of pointer movement at 30 fps):timeout— milliseconds a browser step may take, and ffmpeg may go without reporting progress (default30_000)
:persist— keyword list controllingPhoenixReplay.Session.Finalizer::attempts— save attempts before giving up (default3):backoff— base delay in milliseconds, multiplied by the attempt number (default1_000)
Switching options off and overriding them
:flush, :logs, :pointer, :state, :export, :redact,
:max_memory and the client's :landing and :media can be switched off with nil
or false.
For :flush, :logs, :pointer, :state, :export and :landing, true turns
one on with whatever is already set, or its defaults, and a keyword list
sets some of its settings onto that, as :keep, :retention and
:persist do. So a live session's {PhoenixReplay.Recorder, flush: [events: 50]} keeps the application's :interval. :redact and
:max_memory have no defaults to turn on: give them a value.
Tail sampling
:sample_rate decides when a session mounts whether it is recorded.
:keep decides when it ends whether it is saved: a session with an
error, a mark or a slow event matching :errors, :marks or
:slower_than is always saved, a session without user interaction is discarded, and :rate of
the rest are saved.
To save every failing session but only a few others, record every session and keep a share of them:
config :phoenix_replay,
sample_rate: 1.0,
keep: [rate: 0.05, errors: true, slower_than: 1_000],
max_memory: 256 * 1024 * 1024Every session is then buffered until it ends, so set :max_memory.
Summary
Types
A PhoenixReplay.Collector and its options.
A media setting a viewport may carry; see PhoenixReplay.Recording.viewport/0.
A PhoenixReplay.Redactor module and its options.
A storage backend module and its options.
Functions
Loads and validates configuration from the application environment.
Builds a configuration from a keyword list.
Types
A PhoenixReplay.Collector and its options.
@type export() :: %{ endpoint: module() | nil, frame_layout: {module(), atom()} | nil, dir: Path.t() | nil, ttl: pos_integer(), max_concurrency: pos_integer(), queue: module() | {module(), keyword()} | nil, fps: pos_integer(), max_dpr: pos_integer(), idle: pos_integer() | nil, hold: non_neg_integer(), crf: non_neg_integer(), preset: String.t(), ffmpeg: String.t(), playwright: keyword(), max_shots: pos_integer(), timeout: pos_integer() }
@type flush() :: %{events: pos_integer(), interval: pos_integer()}
@type keep() :: %{ rate: float(), errors: boolean(), marks: boolean(), slower_than: pos_integer() | nil }
@type logs() :: %{level: Logger.level(), metadata: [atom()], limit: pos_integer()}
@type media() :: :color_scheme | :reduced_motion | :contrast | :pointer | :hover
A media setting a viewport may carry; see PhoenixReplay.Recording.viewport/0.
@type persist() :: %{attempts: pos_integer(), backoff: non_neg_integer()}
@type pointer() :: %{ sample: pos_integer(), scroll: pos_integer(), flush: pos_integer(), max_points: pos_integer(), limit: pos_integer() }
A PhoenixReplay.Redactor module and its options.
@type retention() :: %{ max_age: pos_integer() | nil, max_count: non_neg_integer() | nil, interval: pos_integer() }
@type state() :: %{ flush: pos_integer(), max_entries: pos_integer(), max_key: pos_integer(), max_entry_bytes: pos_integer(), max_bytes: pos_integer(), limit: pos_integer(), inputs: boolean(), debounce: pos_integer() }
A storage backend module and its options.
@type t() :: %PhoenixReplay.Config{ client: client(), collect: [collector()], export: export() | nil, flush: flush() | nil, keep: keep(), logs: logs() | nil, max_events: pos_integer(), max_memory: pos_integer() | nil, persist: persist(), pointer: pointer() | nil, redact: redactor() | nil, release: String.t() | nil, replay: module() | nil, retention: retention(), sample_rate: float(), sanitizer: module(), state: state() | nil, storage: storage() }
Functions
Loads and validates configuration from the application environment.
overrides take precedence over the environment. Module-keyed entries,
such as an endpoint configured with otp_app: :phoenix_replay, belong to
those modules and are skipped.
It runs on every request and mount, so the result is kept for each set
of overrides and built again only when the environment changes.
Builds a configuration from a keyword list.
Raises ArgumentError for unknown keys or invalid values.