# Configuration

## Application
{: .col-2}

### Storage

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

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

### Sanitizer

```elixir
config :phoenix_replay, sanitizer: MyApp.ReplaySanitizer
```

Default: `PhoenixReplay.Sanitizer.Default`.

### Sampling

```elixir
config :phoenix_replay, sample_rate: 0.25
```

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

### Event limit

```elixir
config :phoenix_replay, max_events: 10_000
```

LiveView events kept per session. Default: `10_000`.

### Tail sampling

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

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

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

Off by default.

### Redaction

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

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

### Obscura

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

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

### Writing running sessions

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

```elixir
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](recording.md#pointer-touches-and-scrolling).

### Client state

```elixir
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](recording.md#client-state).

### Releases

```elixir
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](recording.md#older-recordings).

### How recordings replay

```elixir
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](recording.md#older-recordings).

### Video export

```elixir
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](dashboard.md#exporting-videos).

### Retention

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

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

Backoff in milliseconds, multiplied by the attempt number.

## Install and testing
{: .col-2}

### Install

```bash
mix igniter.install phoenix_replay
```

### Recording off in tests

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

## Browser context
{: .col-2}

### LiveSocket

```javascript
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

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

### Visit context

```elixir
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
{: .col-2}

### Record a live session

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

### Per-session options

```elixir
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
{: .col-2}

### Mount the dashboard

```elixir
import PhoenixReplay.Router

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

### Authentication and authorization

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

### Frame layout

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

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

### Socket path

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

Default: `"/live"`.

### Mount twice

```elixir
phoenix_replay "/replay", as: :staff_replay
```

## Dashboard filters
{: .col-2}

### Parameters

| Parameter | Matches |
|---|---|
| `q` | Text in URL, id, event or mark names, source or campaign |
| `view` | View module name |
| `event` | Triggered event name |
| `mark` | A mark the session reached |
| `source`, `medium`, `campaign` | Where the visit came from |
| `device_type` | `phone`, `tablet` or `desktop` |
| `browser` | Browser family, such as `Mobile Safari` |
| `release` | The release it was recorded on |
| `within` | `15m`, `1h`, `24h`, `7d` or `30d` |
| `from`, `to` | Start time range, ISO 8601 in UTC |
| `longer_than` | Minimum duration in seconds |
| `min_events` | Minimum event count |
| `errors` | `1` for sessions with an error |
| `tab` | One browser tab's sessions |

### In code

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

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