PhoenixReplay.Config (PhoenixReplay v0.6.2)

Copy Markdown View Source

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} implementing PhoenixReplay.Storage. Defaults to {PhoenixReplay.Storage.File, []}.
  • :sanitizer — module implementing PhoenixReplay.Sanitizer. Defaults to PhoenixReplay.Sanitizer.Default.
  • :max_events — events recorded per session before recording stops. Defaults to 10_000.
  • :sample_rate — share of sessions to record, from 0.0 to 1.0. Defaults to 1.0, recording every session. 0.0 turns 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 (default 1.0)
    • :errors — always save sessions with an error (default false)
    • :marks — always save sessions with a telemetry event collected with mark: true, such as a completed checkout (default false)
    • :slower_than — always save sessions with a collected event lasting at least this many milliseconds (default nil)
  • :collect — telemetry events to record alongside LiveView events. Each entry is a PhoenixReplay.Collector module, {module, opts}, an event name, or {event_name, opts} for PhoenixReplay.Collector.Generic. Every entry accepts :limit, the events recorded per session (default 1_000). Defaults to [].
  • :logs — keyword list enabling Logger collection, or nil (the default) to leave logs out. See PhoenixReplay.Capture.Logs.
  • :redact — a PhoenixReplay.Redactor that masks sensitive values when a recording is saved: a list of regexes, or regex sources as strings, for PhoenixReplay.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 (see PhoenixReplay.Storage), or false to save each session only when it ends:
    • :events — events buffered before a chunk is written (default 200)
    • :interval — milliseconds after which buffered events are written anyway (default 5_000)
  • :pointer — records the pointer, touches and scrolling, for the player to show over the replay, when the client module's replayRecorder/1 runs in the browser. true uses the defaults; a keyword list sets any of them; false (the default) records none:
    • :sample — milliseconds between recorded pointer positions (default 50)
    • :scroll — milliseconds between recorded scroll positions (default 100)
    • :flush — milliseconds between the batches the browser sends (default 1_000)
    • :max_points — positions, presses and scrolls a batch may hold; a fuller batch is sent early, and the server drops the rest (default 500)
    • :limit — batches recorded per session (default 3_600, an hour of movement at the default :flush)
  • :state — records state that lives only in the browser, when the client module's replayRecorder/1 runs: what is typed and chosen in form controls, and what app code reports with replayState/2; see PhoenixReplay.Capture.State. On by default; false records none, and a keyword list sets any of:
    • :inputs — whether form controls are recorded (default true). 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 (default 300)
    • :flush — milliseconds between the batches the browser sends (default 1_000)
    • :max_entries — entries a batch may hold; a fuller batch is sent early, and the server drops the rest (default 200)
    • :max_key — bytes a key may have (default 64)
    • :max_entry_bytes — the JSON size an entry's changes may have; larger ones are dropped (default 8_192)
    • :max_bytes — the JSON size a batch may have; a fuller batch is sent early, and the server drops the rest (default 65_536)
    • :limit — batches recorded per session (default 3_600)
  • :client — what recordings keep in client about the browser and the visit. :context is 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, :pointer and :hover (default all of them), or false for none. See "What the browser sends" in the privacy guide
    • :headers — request header names to capture, refreshed on each request (default []). cookie, authorization and proxy-authorization are refused.
    • :landing — keyword list capturing the visit's landing request, or nil (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 — true keeps the Referer without its query string, :full keeps all of it, false none (default true)
      • :attribution — :first keeps the first landing of the visit; :last replaces 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; see PhoenixReplay.Recording.Code.
  • :replay — a PhoenixReplay.Replay module adapting how recordings replay, such as the assigns older recordings hold, or nil (the default).
  • :max_memory — bytes of buffered recordings above which new sessions are not recorded, or nil (the default) for no limit.
  • :retention — keyword list controlling PhoenixReplay.Storage.Retention:
    • :max_age — milliseconds after which recordings are deleted
    • :max_count — number of most recent recordings to keep
    • :interval — milliseconds between pruning runs (default 60_000)
  • :export — video export with PhoenixReplay.Export, off by default. A keyword list turns it on; :endpoint is 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 (default phoenix_replay/exports in the system's temporary directory)
    • :ttl — milliseconds a finished video is kept (default 3_600_000)
    • :max_concurrency — videos exported at once; more wait their turn (default 1). PhoenixReplay.Export.Queue.Oban takes its limit from its Oban queue instead.
    • :queue — where exports wait and run, a PhoenixReplay.Export.Queue: a module or {module, opts} (default PhoenixReplay.Export.Queue.Local)
    • :fps — frames per second (default 30)
    • :max_dpr — the highest device pixel ratio to render at, which bounds the video's size (default 2)
    • :idle — milliseconds a stretch without activity is shortened to, or nil to keep it whole (default 3_000)
    • :hold — milliseconds the last moment is held at the end (default 1_000)
    • :crf — the H.264 quality, lower is better (default 23)
    • :preset — the x264 speed preset (default "veryfast")
    • :ffmpeg — the ffmpeg executable (default "ffmpeg")
    • :playwright — options for PlaywrightEx.Supervisor, such as :executable or :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 (default 3_600, two minutes of pointer movement at 30 fps)
    • :timeout — milliseconds a browser step may take, and ffmpeg may go without reporting progress (default 30_000)
  • :persist — keyword list controlling PhoenixReplay.Session.Finalizer:
    • :attempts — save attempts before giving up (default 3)
    • :backoff — base delay in milliseconds, multiplied by the attempt number (default 1_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 * 1024

Every session is then buffered until it ends, so set :max_memory.

Summary

Types

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.

t()

Functions

Loads and validates configuration from the application environment.

Builds a configuration from a keyword list.

Types

client()

@type client() :: %{headers: [String.t()], landing: landing() | nil, media: [media()]}

collector()

@type collector() :: {module(), keyword()}

A PhoenixReplay.Collector and its options.

export()

@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()
}

flush()

@type flush() :: %{events: pos_integer(), interval: pos_integer()}

keep()

@type keep() :: %{
  rate: float(),
  errors: boolean(),
  marks: boolean(),
  slower_than: pos_integer() | nil
}

landing()

@type landing() :: %{
  params: [String.t()],
  referrer: boolean() | :full,
  attribution: :first | :last
}

logs()

@type logs() :: %{level: Logger.level(), metadata: [atom()], limit: pos_integer()}

media()

@type media() :: :color_scheme | :reduced_motion | :contrast | :pointer | :hover

A media setting a viewport may carry; see PhoenixReplay.Recording.viewport/0.

persist()

@type persist() :: %{attempts: pos_integer(), backoff: non_neg_integer()}

pointer()

@type pointer() :: %{
  sample: pos_integer(),
  scroll: pos_integer(),
  flush: pos_integer(),
  max_points: pos_integer(),
  limit: pos_integer()
}

redactor()

@type redactor() :: {module(), keyword()}

A PhoenixReplay.Redactor module and its options.

retention()

@type retention() :: %{
  max_age: pos_integer() | nil,
  max_count: non_neg_integer() | nil,
  interval: pos_integer()
}

state()

@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()
}

storage()

@type storage() :: {module(), keyword()}

A storage backend module and its options.

t()

@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

load(overrides \\ [])

@spec load(keyword()) :: t()

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.

new(opts)

@spec new(keyword()) :: t()

Builds a configuration from a keyword list.

Raises ArgumentError for unknown keys or invalid values.