# `PhoenixReplay.Config`
[🔗](https://github.com/elixir-vibe/phoenix_replay/blob/v0.6.2/lib/phoenix_replay/config.ex#L1)

Validated runtime configuration.

This is the only module that reads the `:phoenix_replay` application
environment. Everything else receives a `t: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`.

# `client`

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

# `collector`

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

A `PhoenixReplay.Collector` and its options.

# `export`

```elixir
@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`

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

# `keep`

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

# `landing`

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

# `logs`

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

# `media`

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

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

# `persist`

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

# `pointer`

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

# `redactor`

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

A `PhoenixReplay.Redactor` module and its options.

# `retention`

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

# `state`

```elixir
@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`

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

A storage backend module and its options.

# `t`

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

# `load`

```elixir
@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`

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

Builds a configuration from a keyword list.

Raises `ArgumentError` for unknown keys or invalid values.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
