PhoenixReplay.Collector behaviour (PhoenixReplay v0.6.2)

Copy Markdown View Source

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

Summary

Callbacks

Captures an event, or skips it.

The telemetry events to attach to.

Functions

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

Converts time measurements from native units to milliseconds.

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

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

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

Callbacks

capture(event, measurements, metadata, opts)

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

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

The telemetry events to attach to.

Functions

error(kind, reason)

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

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

milliseconds(measurements)

@spec milliseconds(map()) :: %{required(atom()) => 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(event)

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

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

result_error(arg1)

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

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

to_milliseconds(native)

@spec to_milliseconds(number()) :: number()

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