Session Domain
The Session domain defines methods for using recording sessions. In order to
inspect a recording, it must first be loaded into a session via
Recording.createSession.
After the session is created, it may be in an unprocessed or partially processed state. As documented, some commands do not return until the session has fully processed the recording. Processing starts automatically after the session is created.
All commands and events in this domain must include a sessionId.
Methods
Events
Types
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.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
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:
- It does not require the creation of a Pause, making it much faster.
- 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:
- This takes time to compute, so we recommend that clients progressively load groups of stack frames.
- 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.CallStacktype, 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.findPointsand 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
- Only mutate properties if the object was explicitly created by the evaluated expressions themselves, and never trigger getter properties.
- Only call functions created by the evaluated expressions themselves.
- 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.RunEvaluationPreloadfor 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.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.
begin, endType: 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.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.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