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

Behaviour for recording `:telemetry` events alongside LiveView events.

A collector names the events it listens to and turns each one into a
`PhoenixReplay.Collector.Captured` struct, or skips it. Collectors are configured under
`:collect`:

    config :phoenix_replay,
      collect: [
        {PhoenixReplay.Collector.Ecto, repo: MyApp.Repo, slower_than: 5},
        PhoenixReplay.Collector.Finch,
        {[:my_app, :checkout, :stop], metadata: [:order_id]}
      ]

A bare event name, or `{event_name, opts}`, is shorthand for
`PhoenixReplay.Collector.Generic`.

`PhoenixReplay.Capture.TelemetryEvents` attaches every collector when the
application starts and records what it captures in the session of the
process that emitted the event, or of the process that started it
through `Task` (its `$callers`). Events from processes that belong to no
recorded session cost one ETS lookup per caller. Captured data then goes
through the session's `PhoenixReplay.Sanitizer` and `:redact` patterns,
and at most `:limit` events per collector are recorded for each session.

`capture/4` runs in the process that emitted the event, so it should be
cheap. Keep only the metadata a reader of the replay needs: metadata
often holds whole sockets, connections and structs.

## Example

    defmodule MyApp.PaymentCollector do
      @behaviour PhoenixReplay.Collector

      alias PhoenixReplay.Collector
      alias PhoenixReplay.Collector.Captured

      @impl true
      def events(_opts), do: [[:my_app, :payment, :stop]]

      @impl true
      def capture(_event, measurements, metadata, _opts) do
        {:ok,
         %Captured{
           summary: "charge #{metadata.amount} #{metadata.currency}",
           measurements: Collector.milliseconds(measurements),
           metadata: Map.take(metadata, [:provider])
         }}
      end
    end

# `capture`

```elixir
@callback capture(
  event :: :telemetry.event_name(),
  measurements :: map(),
  metadata :: map(),
  opts :: keyword()
) :: {:ok, PhoenixReplay.Collector.Captured.t()} | :skip
```

Captures an event, or skips it.

# `events`

```elixir
@callback events(opts :: keyword()) :: [:telemetry.event_name()]
```

The telemetry events to attach to.

# `error`

```elixir
@spec error(atom(), term()) :: String.t()
```

Describes an `:exception` event's `kind` and `reason` in one line.

# `milliseconds`

```elixir
@spec milliseconds(map()) :: %{required(atom()) =&gt; number()}
```

Converts time measurements from native units to milliseconds.

`:duration` and keys ending in `_time` are converted, following the
conventions of `:telemetry.span/3`, Phoenix and Ecto. `:monotonic_time`
and `:system_time` are timestamps rather than durations and are dropped.
Other numbers are kept as they are.

# `name`

```elixir
@spec name(:telemetry.event_name()) :: String.t()
```

Joins an event name with dots, as in `"my_app.repo.query"`.

# `result_error`

```elixir
@spec result_error(term()) :: String.t() | nil
```

Describes the error in an `{:error, reason}` result, or returns `nil` for other results.

# `to_milliseconds`

```elixir
@spec to_milliseconds(number()) :: number()
```

Converts a native time unit integer to milliseconds, rounded to microseconds.

---

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