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
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
@callback capture( event :: :telemetry.event_name(), measurements :: map(), metadata :: map(), opts :: keyword() ) :: {:ok, PhoenixReplay.Collector.Captured.t()} | :skip
Captures an event, or skips it.
@callback events(opts :: keyword()) :: [:telemetry.event_name()]
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.
: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.
@spec name(:telemetry.event_name()) :: String.t()
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.