Record Replay Protocol

Methods

Session.createPause

Create a pause describing the state at an execution point.

parameters
point
Recording.ExecutionPoint

Point to create the pause at.

Return Object
pauseId
Pause.PauseId

Identifier for the new pause.

Session.ensureProcessed

Does not return until the recording is fully processed.

Session.ensureRoutineAnnotations

Does not return until routines have run on the recording and the resulting annotations have been stored. This is a highly experimental command that may change at any time.

Session.experimentalCommand

Perform an operation on this session which is not yet officially supported in the protocol.

parameters
name
string
params
object
Return Object
rval
object

Session.findAnnotations

Find all points in the recording at which an annotation was added via the RecordReplayOnAnnotation driver API. Does not return until the recording is fully processed. Before returning, annotations events will be periodically emitted which describe all annotations of the provided kind.

parameters
kind
string

Any kind to restrict the returned annotations to.

Session.findKeyboardEvents

Find all points in the recording at which a keyboard event occurred. Does not return until the recording is fully processed. Before returning, keyboardEvents events will be periodically emitted. The union of all these events describes all keyboard events in the recording.

Session.findMouseEvents

Find all points in the recording at which a mouse move or click occurred. Does not return until the recording is fully processed. Before returning, mouseEvents events will be periodically emitted. The union of all these events describes all mouse events in the recording.

Session.findNavigationEvents

Session.findPoints

Resolve a selector to a set of points. Zero or more Session.findPointsResults events will be emitted with points matching the query, in point order.

parameters
findPointsId
FindPointsId

The ID of the findPoints results.

pointSelector
PointSelector

The selector to choose points. This selector will run with additional limits provided by:

  • The 'pointLimits' argument.
  • The current focus window range.
  • The backend's implicit maximum point limit.
pointLimits
PointPageLimits

A page description to limit the point selector to a given recording range.

Return Object
nextBegin
Recording.ExecutionPoint

If the point search stopped due to hitting the max point limit, this is set to indicate the next pointLimits 'begin' value that a client may use to query more points.

Session.getAnnotationKinds

Get the different kinds of annotations in the recording.

Return Object
kinds
array[ string ]

Session.getBuildId

Get the identifier of the build used to produce the recording.

Return Object
buildId
string

Build identifier originally passed to the RecordReplayAttach API when recording. The build ID includes the platform, target (e.g. gecko, chromium, or node), build date, and a unique identifier. The format of a build ID is not currently consistent between platforms, and is subject to change over time.

Session.getEndpoint

Get the last execution point in the recording.

Return Object
endpoint
Recording.TimeStampedPoint

Session.getFocusWindow

Return Object
window
Recording.TimeStampedPointRange

Focus window.

Session.getPointFrameSteps

Get the points of all steps that are executed by the frame which a point is part of. This behaves the same as Pause.getFrameSteps but does not require creating a pause and is much faster.

parameters
point
Recording.ExecutionPoint

Point to get frame steps for.

Return Object
steps
array[ Debugger.PointDescription ]

Execution points for all steps which the frame executes.

Session.getPointNearTime

Get a point near a given time in the recording. Unlike other commands, this command will not raise an error if it is performed for an unloaded time.

parameters
time
number
Return Object
point
Recording.TimeStampedPoint

Session.getPointsBoundingTime

Get points bounding a time. Much like getPointNearTime, this command will not raise an error if it is performed for an unloaded time.

parameters
time
number
Return Object
after
Recording.TimeStampedPoint
before
Recording.TimeStampedPoint

Session.getPointStack

Builds a callstack-analogous structure starting from the input point.

NOTE: This result is built from our ExecutionPoint dataset, and is thus different from Pause.getAllFrames in two important ways:

  1. It does not require the creation of a Pause, making it much faster.
  2. The stack entries represent known points in our dataset, but we don't have ExecutionPoints for every possible location, so any frame entries will be the closest point available in the callee frame.
parameters
point
Recording.ExecutionPoint

Point to begin traversal at.

maxCount
integer

The max number of entries to return. NOTE: This field is required because:

  1. This takes time to compute, so we recommend that clients progressively load groups of stack frames.
  2. The depth of the stack can't be known ahead of time, so it is best if clients set realistic limits on how many entries to request.
Return Object
frames
array[ PointStackFrame ]

The list of frames, which may be empty.

hitFocusBegin
boolean

If the focus window excluded data that was necessary to determine whether or not further frames exist, this will be set.

Session.hasAnnotationKind

Check whether any annotations with the given kind exist.

parameters
kind
string
Return Object
hasKind
boolean

Session.listenForLoadChanges

Listen for changes in the loading status of parts of the recording. Does not return until the session has been released. Before returning, loadedRegions events will be emitted when their status changes. By default, the entire recording is loaded. If the recording is long enough, earlier loaded regions may be unloaded to reduce backend resource usage. Pauses cannot be created or used in unloaded parts of the recording, and execution information for Session.findPoints, Session.runEvaluation, and other commands like Debugger.getHitCounts will not be available.

Session.listenForProcessingProgress

Listen for updates about the recording's processing. Does not return until the recording has been fully processed. Before returning, processingProgress events will be emitted whenever a new region in the recording is processed. This command is experimental and it may change or be removed at any time.

Session.releasePause

Release a pause and allow its resources to be reclaimed.

parameters
pauseId
Pause.PauseId

Session.requestFocusRange

Request to load a range between two timestamps. This command will unload areas outside of the requested range.

After this command returns, any future commands that are sent will use the new loading range, and might need to wait until it finishes loading before they return.

Commands which are sent before this returns or which were still in progress when this was sent may use either the earlier loaded range, the newly loaded range, or some combination of the two.

parameters
range
FocusWindowRequest

Range to load.

Return Object
window
Recording.TimeStampedPointRange

Focus window.

Session.requestFocusWindow

Request to load a range between two execution points. This command will unload areas outside of the requested range.

After this command returns, any future commands that are sent will use the new loading range, and might need to wait until it finishes loading before they return.

Commands which are sent before this returns or which were still in progress when this was sent may use either the earlier loaded range, the newly loaded range, or some combination of the two.

parameters
request
PointRangeFocusRequest

Description of the focus window requested.

Return Object
window
Recording.TimeStampedPointRange

The focus window that was applied.

Session.runEvaluation

Perform an evaluation at many points throughout the recording. Zero or more Session.runEvaluationResults events will be emitted with results matching the query, with no ordering guarantees.

parameters
runEvaluationId
RunEvaluationId

The ID of the evaluation.

pointSelector
PointSelector

The selector to choose what points to evaluate at. This selector will run with additional limits provided by:

  • The 'pointLimits' argument.
  • The current focus window range.
  • The backend's implicit maximum point limit.
pointLimits
PointPageLimits

A page description to limit the point selector to a given recording range.

expression
string

The expression to evaluate.

frameIndex
integer

The index of the frame to evaluate in, with negative values wrapping back around. Omitted to evaluate in the global scope. This value indexes into the Pause.CallStack type, so for example: Examples: 0 -> The frame that is currently executing, i.e. the top-most frame. N-1 or -1 -> The shallowest frame's scope, i.e. the frame with no parent. Omitted -> The global scope.

fullReturnedPropertyPreview
boolean

By default the result value will be returned as a "full" preview and nested values will canOverflow and so on. This may be set to true to request that the backend attempt to expand the properties of the returned result to also be full previews. This is only a best effort and the backend does not guarantee that all properties will have been expanded.

shareProcesses
boolean

By default, evaluations are executed in independent processes, so the results will be similar to what you'd expect calling Session.findPoints and then indiviually creating Pause objects at each point. This is guaranteed to be safe, but means that evaluations can be quite slow on large numbers of points.

This flag switches our evaluation infrastructure to instead perform the evaluations inline as a process runs forward, which can be significantly faster, however this comes with much stricter expectations around what operations the evaluations may perform.

In practice, this primarily means that evaluations must not have any side-effects that would cause the recorded process to behave differently from how it behaved when it was recorded. The difficulty here is that it is often quite hard to know ahead of time what things do and do not cause divergences in behavior, because replay recordings at a very low level. As such it is very hard for us to make any guarantees about behavior when using this flag.

As a good rule of thumb, evaluations performed with this flag enabled should aim to consider the entire JS environment as read-only except for code loaded by the evaluated expressions. Thus

  1. Only mutate properties if the object was explicitly created by the evaluated expressions themselves, and never trigger getter properties.
  2. Only call functions created by the evaluated expressions themselves.
  3. Never directly or indirectly call global libraries provided by the browser, like 'console.log' or 'new Date', which may internally mutate browser state held outside the JS engine.

These restrictions also apply during generation of the full protocol response PauseData values, so clients should either limit their result values to primitive types, or ensure that objects in the result are not at risk of triggerig the above cases when generating previews.

Additionally, when this flag is enabled, the pauseIds returned for each evaluation result are not currently usable with pause commands.

NOTE: This flag is not presently supported consistently across our target runtimes. Evaluations with this enabled on unsupported builds will trigger a build compatibility exception.

singleProcess
boolean

A stricter alternative to shareProcesses which guarantees the evaluations are all performed within the same process. Any side effects from an earlier evaluation will be present in later evaluations.

preloadExpressions
array[ RunEvaluationPreload ]

An array of expression preloads to expose for this evaluation. See Session.RunEvaluationPreload for more info.

Return Object
nextBegin
Recording.ExecutionPoint

If the point search stopped due to hitting the max point limit, this is set to indicate the next pointLimits 'begin' value that a client may use to query more points.

Events

Session.annotations

Describes some annotations in the recording.

parameters
annotations
array[ Recording.Annotation ]

Session.findPointsResults

Inform clients of points matching the query. A single Session.findPoints command will emit zero or more of these events, in point order.

parameters
findPointsId
FindPointsId

The ID of the find that these points apply to.

points
array[ Debugger.PointDescription ]

A list of points found when searching. Guaranteed to be sorted.

Session.keyboardEvents

Describes some keyboard events that occur in the recording.

parameters
events
array[ Recording.KeyboardEvent ]

Session.loadedRegions

Describes the regions of the recording which are loading or loaded.

parameters
loaded
array[ Recording.TimeStampedPointRange ]

Timespans which are fully loaded.

loading
array[ Recording.TimeStampedPointRange ]

Timespans which are in the process of loading. Pauses in these regions can still be used, but will be slower.

indexed
array[ Recording.TimeStampedPointRange ]

Timespans which have been indexed. Note: Indexed timespans are a subset of loading in the same way that loaded is a subset of loading.

Session.mayDestroy

Notify clients if the backend expects to destroy the session due to inactivity. Clients are expected to present the user with a notification to allow them to cancel the pending destroy.

Clients may assume that this will be a one-time notification for each period of inactivity, meaning that the destroy time will not change unless the pending destroy was cancelled and a new period of inactivity arose.

Clients may assume that they will not receive this notification more than 30 minutes before the session is destroyed. The API will aim to provide a minimum of several minutes of lead time to allow a user to provide input to cancel the pending destroy.

Clients can expect a Recording.sessionError event when the session is destroyed.

parameters
time
Connection.CloseTimestamp

The time when the backend expects to destroy the session, or omitted to indicate that a previous pending destroy has been cancelled.

Session.mouseEvents

Describes some mouse events that occur in the recording.

parameters
events
array[ Recording.MouseEvent ]

Session.navigationEvents

Describes some navigate events that occur in the recording.

parameters
events
array[ Recording.NavigationEvent ]

Session.processingProgress

Describes processing state for the recording.

parameters
progressPercent
number

The percentage of the recording that has been processed.

Session.runEvaluationResults

Inform the client that some subset of the point evaluations has completed. Note: No event ordering of these responses is enforced, results will be sent as soon as they are available.

parameters
runEvaluationId
RunEvaluationId

The ID of the evaluation that these results apply to.

results
array[ RunEvaluationResult ]

The list of evaluations that have just completed, with unspecified order.

Session.willDestroy

Notify clients if the backend expects to explicitly destroy a session with no recourse for the user.

Clients should handle the possibility of multiple events, but may assume that the remaining time will only decrease in further events.

Clients may assume that they will not receive this notification more than 30 minutes before the session is destroyed. No explicit expectations are placed on how much time clients will be given before the session is destroyed, but sufficient time for a user to react and load a new session is the goal.

Clients can expect a Recording.sessionError event when the session is destroyed.

parameters
time
Connection.CloseTimestamp

The time when the backend expects to destroy the session.

Types

Session.EventHandlerEntrypointSelector

Select the entry point of every handler for an event.

Type: object

properties
kind
"event-handlers"
eventTypes
array[ Debugger.EventHandlerType ]

Type of event whose handler calls should be selected.

Session.ExceptionPointSelector

Select every point where an exception is thrown.

Type: object

properties
kind
"exceptions"

Session.FindPointsId

The ID type for Session.findPoints commands.

Type: string

Session.FocusWindowRequest

Description for the focus window to load within a recording.

Type: object

properties
begin
Recording.TimeStamp

The earliest time to request be loaded. Defaults to 0.

end
Recording.TimeStamp

The latest time to request be loaded. Defaults to the recording endpoint time.

bias
FocusWindowRequestBias

Request a particular bias for how the window should be selected, in cases where the server opts to load a window that is smaller than the requested time range. Defaults to "end".

Session.FocusWindowRequestBias

Defines the possible bias values for the focus window request.

Allowed Values: begin, end

Type: string

Session.FrameStepsSelector

Select all frame steps matching some criteria.

Type: object

properties
kind
"frame-steps"
onlyFrameEntry
boolean

Only return points at the beginning of a frame.

locationLimit
number

Maximum number of points to return for the same location.

minFrameDepth
number

Minimum frame depth for returned points.

maxFrameDepth
number

Maximum frame depth for returned points.

Session.PointListSelector

Select a specific set of points.

Type: object

properties
kind
"points"
points
array[ Recording.ExecutionPoint ]

Points to select.

Session.PointLocationSelector

Select every point where a source location executes.

Type: object

properties
kind
"location"
location
Debugger.Location

Location to search for.

onStackFrame
Recording.ExecutionPoint

Limit the points to only those with this point on-stack.

Session.PointLocationsSelector

Select every point where a set of source locations executes.

Type: object

properties
kind
"locations"
locations
array[ Debugger.Location ]

Locations to search for.

Session.PointPageLimits

Describes filtering limits on a list of points.

Type: Recording.PointLimits

properties
maxCount
integer

The maximum number of points to include in the results, counting from the earliest point forward.

Session.PointRangeFocusRequest

Description for the focus window to load within a recording, specified with timestamped points.

Type: object

properties
begin
Recording.TimeStampedPoint

The earliest point to be loaded. Defaults to the first point in the recording.

end
Recording.TimeStampedPoint

The latest point to be loaded. Defaults to the last point in the recording.

bias
FocusWindowRequestBias

Request a particular bias for how the window should be selected, in cases where the server opts to load a window that is smaller than the requested time range. Defaults to "end".

Session.PointSelector

Type: object

Session.PointStackFrame

A descriptor of a frame with basic point data.

Type: object

properties
functionLocation
Debugger.MappedLocation

The location of the function of the stack frame.

point
Debugger.PointDescription

The closest preceding point in the stack frame. Optional because there is no guarantee that the stack frame will have a preceding point to debug.

Session.RunEvaluationId

The ID type for Session.runEvaluation commands.

Type: string

Session.RunEvaluationPreload

A preload expression is an expression that will be evaluated in the global scope and then used by an evaluation. This allows us to perform a few optimizations to make evaluation faster.

If 'shareProcesses' is not enabled, this primarily allows things to be slightly faster by allowing us to amortize parsing costs for large expression, because while we still need to evaluate it at every point, we can load/parse the expression ahead of time.

If 'shareProcesses' is enabled, we're also able to evaluate the preload a single time and reused that value across multiple points. We guarantee that an evaluated preload will always be used for a contiguous monotonic sequence of the input points, but we make no guarantees about how many of these independent sequences there will be, or how each sequence will be determined, unless the 'singleProcess' flag is set in which case there will be a single sequence.

Type: object

properties
name
string

The name to expose in the evaluation scope.

expression
string

An expression to evaluate to get a value.

Session.RunEvaluationResult

Describes the result of an evaluation at a particular point.

Type: Pause.Result

properties
point
Debugger.PointDescription

The point where the evaluation occurred.

pauseId
Pause.PauseId

The id of the pause created during execution.

Session.SessionId

Unique identifier for a session which a recording has been loaded into.

Type: string