PhoenixReplay.Storage behaviour (PhoenixReplay v0.6.2)

Copy Markdown View Source

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

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

Types

Events of a chunk with their sequence numbers, which order them.

t()

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

chunk()

Events of a chunk with their sequence numbers, which order them.

t()

Callbacks

append(recording, chunk, keyword)

(optional)
@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.

child_spec(keyword)

(optional)
@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.

clear(keyword)

@callback clear(keyword()) :: :ok | {:error, term()}

delete(id, keyword)

@callback delete(PhoenixReplay.Recording.id(), keyword()) :: :ok | {:error, term()}

fetch(id, keyword)

@callback fetch(PhoenixReplay.Recording.id(), keyword()) ::
  {:ok, PhoenixReplay.Recording.t()} | {:error, term()}

fetch_partial(id, keyword)

(optional)
@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.

histogram(t, pos_integer, page_opts, keyword)

(optional)

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.

list(keyword)

@callback list(keyword()) :: [PhoenixReplay.Recording.Summary.t()]

partials(keyword)

(optional)
@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.

query(t, page_opts, keyword)

(optional)

Reads a page of summaries matching filter, most recent first, and counts every match. See PhoenixReplay.Recording.Filter.page_opts/0.

save(t, keyword)

@callback save(PhoenixReplay.Recording.t(), keyword()) :: :ok | {:error, term()}

values(field, t, page_opts, keyword)

(optional)

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

append(arg, recording, chunk)

@spec append(t(), PhoenixReplay.Recording.t(), chunk()) :: :ok | {:error, term()}

Appends a chunk of a running session. See append/3.

children(arg)

@spec children(t()) :: [Supervisor.child_spec()]

The processes the backend runs. See child_spec/1.

chunked?(arg)

@spec chunked?(t()) :: boolean()

Returns true when the backend takes running sessions in chunks.

clear(arg)

@spec clear(t()) :: :ok | {:error, term()}

Deletes every stored recording.

delete(arg, id)

@spec delete(t(), PhoenixReplay.Recording.id()) :: :ok | {:error, term()}

Deletes a recording by id.

fetch(arg, id)

@spec fetch(t(), PhoenixReplay.Recording.id()) ::
  {:ok, PhoenixReplay.Recording.t()} | {:error, term()}

Fetches a recording by id.

fetch_partial(arg, 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.

histogram(storage, filter, size, page_opts)

Counts recordings by when they started. See histogram/4.

list(arg)

@spec list(t()) :: [PhoenixReplay.Recording.Summary.t()]

Lists stored recording summaries, most recent first.

partials(arg)

@spec partials(t()) :: [PhoenixReplay.Recording.id()]

Lists sessions with chunks this node did not finish. See partials/1.

query(storage, filter, page_opts)

Reads a page of summaries. See query/3.

save(arg, recording)

@spec save(t(), PhoenixReplay.Recording.t()) :: :ok | {:error, term()}

Persists a finished recording.

values(storage, field, filter, page_opts)

Counts the values of a filter's field. See values/4.