PhoenixReplay.Recording.Filter (PhoenixReplay v0.6.2)

Copy Markdown View Source

Criteria for narrowing a list of PhoenixReplay.Recording.Summary structs.

Filters round-trip through URL query parameters, so a filtered dashboard view can be shared as a link:

  • "q" — text found in the recording's URL, id, event names, mark names, source or campaign
  • "view" — exact view module name, such as "MyAppWeb.CheckoutLive"
  • "event" — a handle_event/3 name the session triggered
  • "mark" — the name of a moment the session reached; see PhoenixReplay.Recording.Event.mark_name/1
  • "source", "medium" and "campaign" — where the visit came from, such as "google", "cpc" and "spring"; see PhoenixReplay.Recording.Client.traffic/1
  • "device_type" — "phone", "tablet" or "desktop"
  • "browser" — the browser's family, such as "Mobile Safari"
  • "release" — the release the session was recorded with; see PhoenixReplay.Recording.Code
  • "within" — "15m", "1h", "24h", "7d" or "30d" since the session started
  • "from" and "to" — the session started within this time range, each an ISO 8601 time such as "2026-10-06T14:00:00Z"
  • "longer_than" — a minimum duration, in seconds
  • "min_events" — minimum number of recorded events
  • "errors" — "1" to keep only sessions with an error, such as an error log, a failed query or a crash
  • "tab" — sessions from one browser tab, a user's journey

Blank or invalid parameters are ignored.

Summary

Types

Sessions started in one stretch of time: its start, how many, and how many with an error.

A criterion whose values can be listed and counted, for suggesting them: see values_of/2.

Which page of matching summaries to read

t()

Functions

The start of the stretch of size milliseconds that at falls in, in a time zone utc_offset milliseconds ahead of UTC.

Counts the values of field among the summaries matching filter, ignoring the filter's own criterion on field, so the other values stay on offer: the most common first, at most limit. now is in Unix milliseconds, for "within".

Returns true when no criteria are set.

The criteria whose values can be listed; see field/0.

Builds a filter from string-keyed query parameters.

Counts the summaries matching filter by when they started, in stretches of size milliseconds, earliest first; see bucket/0. Stretches begin at midnights and hours of the viewer's time zone, :utc_offset milliseconds ahead of UTC (default 0); :now is for "within".

Reads a page of summaries, which are ordered most recent first, and counts every summary that matches. See page_opts/0.

Keeps the summaries matching every criterion. now is in Unix milliseconds.

The earliest start time "within" allows at now, in Unix milliseconds, or nil without it.

The stretch of time filter covers at now, in Unix milliseconds: its window, its range, completed by the last 30 days or now where it is open, or the last 30 days without either.

Converts a filter back to query parameters, omitting unset criteria.

The most common of counted values, then by value, at most limit.

The values a summary has for field, such as its view or its event names.

The supported "within" values, shortest first.

Types

bucket()

@type bucket() :: {integer(), pos_integer(), non_neg_integer()}

Sessions started in one stretch of time: its start, how many, and how many with an error.

field()

@type field() ::
  :view
  | :event
  | :mark
  | :source
  | :medium
  | :campaign
  | :device_type
  | :browser
  | :release

A criterion whose values can be listed and counted, for suggesting them: see values_of/2.

page_opts()

@type page_opts() :: [
  now: integer(),
  until: integer() | nil,
  since: integer() | nil,
  offset: non_neg_integer(),
  limit: non_neg_integer(),
  utc_offset: integer()
]

Which page of matching summaries to read:

  • :now — the current time in Unix milliseconds, for "within"
  • :until — only recordings saved at or before this time, so pages stay put while sessions end; see PhoenixReplay.Recording.Summary.stored_at/1
  • :since — only recordings saved after this time
  • :offset and :limit — the slice to return
  • :utc_offset — for counts by start time, how far the viewer's time zone is ahead of UTC, in milliseconds; see histogram/4

t()

@type t() :: %PhoenixReplay.Recording.Filter{
  browser: String.t() | nil,
  campaign: String.t() | nil,
  device_type: PhoenixReplay.Recording.Client.device_type() | nil,
  errors: boolean(),
  event: String.t() | nil,
  from: integer() | nil,
  longer_than: pos_integer() | nil,
  mark: String.t() | nil,
  medium: String.t() | nil,
  min_events: pos_integer() | nil,
  query: String.t() | nil,
  release: String.t() | nil,
  source: String.t() | nil,
  tab: String.t() | nil,
  to: integer() | nil,
  view: String.t() | nil,
  within: String.t() | nil
}

Functions

bucket(at, size, utc_offset \\ 0)

@spec bucket(integer(), pos_integer(), integer()) :: integer()

The start of the stretch of size milliseconds that at falls in, in a time zone utc_offset milliseconds ahead of UTC.

count_values(summaries, field, filter, now, limit)

@spec count_values(
  [PhoenixReplay.Recording.Summary.t()],
  field(),
  t(),
  integer(),
  pos_integer()
) :: [
  {String.t(), pos_integer()}
]

Counts the values of field among the summaries matching filter, ignoring the filter's own criterion on field, so the other values stay on offer: the most common first, at most limit. now is in Unix milliseconds, for "within".

empty?(filter)

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

Returns true when no criteria are set.

fields()

@spec fields() :: [field()]

The criteria whose values can be listed; see field/0.

from_params(params)

@spec from_params(map()) :: t()

Builds a filter from string-keyed query parameters.

histogram(summaries, filter, size, opts)

@spec histogram(
  [PhoenixReplay.Recording.Summary.t()],
  t(),
  pos_integer(),
  page_opts()
) :: [bucket()]

Counts the summaries matching filter by when they started, in stretches of size milliseconds, earliest first; see bucket/0. Stretches begin at midnights and hours of the viewer's time zone, :utc_offset milliseconds ahead of UTC (default 0); :now is for "within".

page(summaries, filter, opts)

Reads a page of summaries, which are ordered most recent first, and counts every summary that matches. See page_opts/0.

select(summaries, filter, now)

Keeps the summaries matching every criterion. now is in Unix milliseconds.

started_after(filter, now)

@spec started_after(t(), integer()) :: integer() | nil

The earliest start time "within" allows at now, in Unix milliseconds, or nil without it.

time_range(filter, now)

@spec time_range(t(), integer()) :: {integer(), integer()}

The stretch of time filter covers at now, in Unix milliseconds: its window, its range, completed by the last 30 days or now where it is open, or the last 30 days without either.

to_params(filter)

@spec to_params(t()) :: %{optional(String.t()) => String.t()}

Converts a filter back to query parameters, omitting unset criteria.

top(counts, limit)

@spec top(
  %{required(String.t()) => pos_integer()} | [{String.t(), pos_integer()}],
  pos_integer()
) :: [
  {String.t(), pos_integer()}
]

The most common of counted values, then by value, at most limit.

values_of(summary, field)

@spec values_of(PhoenixReplay.Recording.Summary.t(), field()) :: [String.t()]

The values a summary has for field, such as its view or its event names.

windows()

@spec windows() :: [String.t()]

The supported "within" values, shortest first.