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

Reads recordings from code: from IEx, a script, a test, or a coding agent
running code in your app. Everything is plain data, to inspect as it is.

    iex> [summary | _] = PhoenixReplay.Trace.find(errors: true, within: "24h")
    iex> PhoenixReplay.Trace.events(summary.id)
    [%{index: 0, at: 0, type: :mount, label: "mount", ...}, ...]
    iex> PhoenixReplay.Trace.state(summary.id, 14)
    %{index: 14, assigns: %{...}, changed: [%{path: "tasks[id: 7].done", ...}], ...}

Indexes are the player's, so `/replay/<id>?at=<index>` in the dashboard
opens the same moment. A session still running is read from the buffer
of the VM that records it, redacted as the dashboard redacts it; call
these functions in that VM to see it. `mix phoenix_replay.list` and
`mix phoenix_replay.show` print them from the command line, for saved
recordings.

# `change`

```elixir
@type change() :: %{
  path: String.t(),
  change: :changed | :added | :removed,
  before: term(),
  after: term()
}
```

A change the event made inside an assign, at a path such as `tasks[id: 7].done`.

# `event`

```elixir
@type event() :: %{
  index: non_neg_integer(),
  at: non_neg_integer(),
  type: PhoenixReplay.Recording.Event.type(),
  label: String.t(),
  error?: boolean(),
  caused_by: non_neg_integer() | nil,
  data: map()
}
```

One event of a recording:

  * `:index` and `:at` — its place in the player and its offset in
    milliseconds from the session's start
  * `:type` — see `PhoenixReplay.Recording.Event`
  * `:label` — one line as the player's event list shows it
  * `:error?` — whether it reports an error: an error log, a failed
    query, or the view's crash
  * `:caused_by` — the index of the interaction it belongs to, the user
    event, navigation, message or mount that caused it, or `nil` for
    that interaction itself
  * `:data` — what was recorded, as `PhoenixReplay.Recording.Event`
    describes it

# `state`

```elixir
@type state() :: %{
  index: non_neg_integer(),
  at: non_neg_integer(),
  event: event(),
  url: String.t() | nil,
  viewport: PhoenixReplay.Recording.viewport() | nil,
  assigns: map(),
  components: map(),
  client_state: map(),
  changed: [change()]
}
```

The view at one moment: the event there, the URL, the viewport, the
view's assigns, the LiveComponents' assigns by `{module, id}`, the state
the browser reported (see `PhoenixReplay.Recording.State`), and what the
event changed.

# `events`

```elixir
@spec events(PhoenixReplay.Recording.t() | PhoenixReplay.Recording.id()) :: [event()]
```

The events of a recording, or of the recording with that id, as the
player lists them. Pointer batches are left out; client state is an
event per report.

# `fetch`

```elixir
@spec fetch(PhoenixReplay.Recording.id(), PhoenixReplay.Config.t()) ::
  {:ok, PhoenixReplay.Recording.t()} | {:error, :not_found}
```

The recording with `id`, from the buffer while it runs or from storage.

# `find`

```elixir
@spec find(keyword(), PhoenixReplay.Config.t()) :: [
  PhoenixReplay.Recording.Summary.t()
]
```

Summaries of the recordings matching `filters`, running sessions first,
then saved ones, most recent first.

  * `:text` — found in the URL, id, event or mark names, source or
    campaign
  * `:view` — the view module, such as `MyAppWeb.CheckoutLive`
  * `:event` — a `handle_event/3` name the session triggered
  * `:mark` — the name of a moment the session reached, such as
    `"my_app.checkout.completed"`
  * `:source`, `:medium` and `:campaign` — where the visit came from,
    such as `"google"`, `"cpc"` and `"spring"`, or `"(direct)"`; see
    `PhoenixReplay.Recording.Client.traffic/1`
  * `:device_type` — `"phone"`, `"tablet"` or `"desktop"`
  * `:browser` — the browser's family, such as `"Mobile Safari"`
  * `:release` — the release the session was recorded with
  * `:within` — `"15m"`, `"1h"`, `"24h"`, `"7d"` or `"30d"` since the
    session started
  * `:from` and `:to` — a `DateTime` the session started at or after,
    and at or before
  * `:longer_than` — lasting at least that many seconds
  * `:min_events` — at least that many events
  * `:errors` — `true` for sessions with an error only
  * `:tab` — the sessions of one browser tab
  * `:live` — `true` for running sessions only, `false` for saved ones
  * `:limit` — how many to return (default `20`)

# `state`

```elixir
@spec state(
  PhoenixReplay.Recording.t() | PhoenixReplay.Recording.id(),
  non_neg_integer()
) :: state()
```

The view at the event at `index`, as the player shows it there: its
assigns, its components, the client state, and what the event changed.

---

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