Behaviour for finished-recording storage, and the facade used to call it.
In-progress recordings live in PhoenixReplay.Session.Buffer. When the
recorded LiveView exits, the recording is saved through the configured
backend.
A backend that implements the optional append/2, fetch_partial/2 and
partials/1 callbacks also receives running sessions in chunks, as
:flush configures, so they survive a crash of the node and their
events leave memory. save/2 then replaces the chunks with the finished
recording. PhoenixReplay.Storage.File implements them; other backends
save each recording once, when it ends.
Built-in backends
PhoenixReplay.Storage.File— one file per recording on disk (default)PhoenixReplay.Storage.Ecto— a database table via an Ecto repo
Configuration
config :phoenix_replay,
storage: {PhoenixReplay.Storage.File, path: "priv/replay_recordings"}Implementing a backend
Callbacks receive the options from the {module, opts} tuple as their last
argument. list/1 must return summaries without decoding full recordings,
ordered most recent first.
The dashboard reads pages through the optional query/3, and the values
its filters suggest, with how many recordings have each, through the
optional values/4, and counts them by when they started for its chart
through the optional histogram/4. Without them, all are worked out
from list/1. A backend that needs a
process, such as a cache, returns it from the optional child_spec/1.
Summary
Callbacks
Appends a chunk of a running session. recording carries the session's
current metadata; the latest appended metadata wins.
A process the backend needs while the application runs, started under PhoenixReplay's supervisor with the backend's options.
Reads the chunks appended for a session, with events ordered by sequence
number. Returns {:error, :not_found} when none were appended.
Counts the recordings matching filter by when they started, in
stretches of a number of milliseconds; see
PhoenixReplay.Recording.Filter.histogram/4, which this must agree
with. page_opts has :now and :utc_offset.
Lists the ids of sessions with appended chunks this node did not finish, leaving out those of another instance still running, such as a Mix task started next to the server.
Reads a page of summaries matching filter, most recent first, and counts
every match. See PhoenixReplay.Recording.Filter.page_opts/0.
The values of a filter's field among the recordings matching the rest
of filter, with how many recordings have each, the most common first.
See PhoenixReplay.Recording.Filter.count_values/5, which this must
agree with; page_opts has :now and :limit. A backend may count
values it cannot query, such as event names, among recent recordings
only.
Functions
Appends a chunk of a running session. See append/3.
The processes the backend runs. See child_spec/1.
Returns true when the backend takes running sessions in chunks.
Deletes every stored recording.
Deletes a recording by id.
Fetches a recording by id.
Reads the chunks appended for a session. See fetch_partial/2.
Counts recordings by when they started. See histogram/4.
Lists stored recording summaries, most recent first.
Lists sessions with chunks this node did not finish. See partials/1.
Reads a page of summaries. See query/3.
Persists a finished recording.
Counts the values of a filter's field. See values/4.
Types
@type chunk() :: [{non_neg_integer(), PhoenixReplay.Recording.Event.t()}]
Events of a chunk with their sequence numbers, which order them.
@type t() :: PhoenixReplay.Config.storage()
Callbacks
@callback append(recording :: PhoenixReplay.Recording.t(), chunk(), keyword()) :: :ok | {:error, term()}
Appends a chunk of a running session. recording carries the session's
current metadata; the latest appended metadata wins.
@callback child_spec(keyword()) :: Supervisor.child_spec()
A process the backend needs while the application runs, started under PhoenixReplay's supervisor with the backend's options.
@callback delete(PhoenixReplay.Recording.id(), keyword()) :: :ok | {:error, term()}
@callback fetch(PhoenixReplay.Recording.id(), keyword()) :: {:ok, PhoenixReplay.Recording.t()} | {:error, term()}
@callback fetch_partial(PhoenixReplay.Recording.id(), keyword()) :: {:ok, PhoenixReplay.Recording.t()} | {:error, term()}
Reads the chunks appended for a session, with events ordered by sequence
number. Returns {:error, :not_found} when none were appended.
@callback histogram( PhoenixReplay.Recording.Filter.t(), pos_integer(), PhoenixReplay.Recording.Filter.page_opts(), keyword() ) :: [PhoenixReplay.Recording.Filter.bucket()]
Counts the recordings matching filter by when they started, in
stretches of a number of milliseconds; see
PhoenixReplay.Recording.Filter.histogram/4, which this must agree
with. page_opts has :now and :utc_offset.
@callback list(keyword()) :: [PhoenixReplay.Recording.Summary.t()]
@callback partials(keyword()) :: [PhoenixReplay.Recording.id()]
Lists the ids of sessions with appended chunks this node did not finish, leaving out those of another instance still running, such as a Mix task started next to the server.
@callback query( PhoenixReplay.Recording.Filter.t(), PhoenixReplay.Recording.Filter.page_opts(), keyword() ) :: {[PhoenixReplay.Recording.Summary.t()], non_neg_integer()}
Reads a page of summaries matching filter, most recent first, and counts
every match. See PhoenixReplay.Recording.Filter.page_opts/0.
@callback save(PhoenixReplay.Recording.t(), keyword()) :: :ok | {:error, term()}
@callback values( PhoenixReplay.Recording.Filter.field(), PhoenixReplay.Recording.Filter.t(), PhoenixReplay.Recording.Filter.page_opts(), keyword() ) :: [{String.t(), pos_integer()}]
The values of a filter's field among the recordings matching the rest
of filter, with how many recordings have each, the most common first.
See PhoenixReplay.Recording.Filter.count_values/5, which this must
agree with; page_opts has :now and :limit. A backend may count
values it cannot query, such as event names, among recent recordings
only.
Functions
@spec append(t(), PhoenixReplay.Recording.t(), chunk()) :: :ok | {:error, term()}
Appends a chunk of a running session. See append/3.
@spec children(t()) :: [Supervisor.child_spec()]
The processes the backend runs. See child_spec/1.
Returns true when the backend takes running sessions in chunks.
Deletes every stored recording.
@spec delete(t(), PhoenixReplay.Recording.id()) :: :ok | {:error, term()}
Deletes a recording by id.
@spec fetch(t(), PhoenixReplay.Recording.id()) :: {:ok, PhoenixReplay.Recording.t()} | {:error, term()}
Fetches a recording by id.
@spec fetch_partial(t(), PhoenixReplay.Recording.id()) :: {:ok, PhoenixReplay.Recording.t()} | {:error, term()}
Reads the chunks appended for a session. See fetch_partial/2.
@spec histogram( t(), PhoenixReplay.Recording.Filter.t(), pos_integer(), PhoenixReplay.Recording.Filter.page_opts() ) :: [PhoenixReplay.Recording.Filter.bucket()]
Counts recordings by when they started. See histogram/4.
@spec list(t()) :: [PhoenixReplay.Recording.Summary.t()]
Lists stored recording summaries, most recent first.
@spec partials(t()) :: [PhoenixReplay.Recording.id()]
Lists sessions with chunks this node did not finish. See partials/1.
@spec query( t(), PhoenixReplay.Recording.Filter.t(), PhoenixReplay.Recording.Filter.page_opts() ) :: {[PhoenixReplay.Recording.Summary.t()], non_neg_integer()}
Reads a page of summaries. See query/3.
@spec save(t(), PhoenixReplay.Recording.t()) :: :ok | {:error, term()}
Persists a finished recording.
@spec values( t(), PhoenixReplay.Recording.Filter.field(), PhoenixReplay.Recording.Filter.t(), PhoenixReplay.Recording.Filter.page_opts() ) :: [{String.t(), pos_integer()}]
Counts the values of a filter's field. See values/4.