Record Replay Protocol

Analysis Domain

The Analysis domain is used to efficiently analyze the program state at many execution points. Analysis specifications are based on the MapReduce algorithm: a map operation is performed on all the execution points of interest, and the results are reduced to a summary afterwards.

The life cycle of an analysis is as follows. First, use createAnalysis to create the analysis and specify its map and reduce operations. Next, use one or more other commands to specify the set of execution points to apply the analysis to. Finally, use runAnalysis to start running the analysis and generate analysisResult events.

All commands and events in this domain must include a sessionId.

Methods

Analysis.addEventHandlerEntryPoints

Analysis.addExceptionPoints

Analysis.addFunctionEntryPoints

Analysis.addLocation

Analysis.addPoints

Analysis.addRandomPoints

Analysis.createAnalysis

Analysis.findAnalysisPoints

Analysis.releaseAnalysis

Analysis.runAnalysis

Events

Analysis.analysisError

Analysis.analysisPoints

Analysis.analysisResult

Types

Analysis.AnalysisEntry

Analysis.AnalysisId

Analysis.AnalysisKey

Analysis.AnalysisValue

Analysis.MapInput

Methods

Analysis.addEventHandlerEntryPoints #

Apply the analysis to the entry point of every handler for an event.

parameters

analysisId: AnalysisId

Associated analysis.
eventType: Debugger.EventHandlerType

Type of event whose handler calls the analysis should be applied to.

Analysis.addExceptionPoints #

Apply the analysis to every point where an exception is thrown.

parameters

analysisId: AnalysisId

Associated analysis.

Analysis.addFunctionEntryPoints #

Apply the analysis to every function entry point in a region of a source.

parameters

analysisId: AnalysisId

Associated analysis.
sourceId: Debugger.SourceId

Source to look for function entry points in.
begin: Debugger.SourceLocation

If specified, earlier functions will be excluded.
end: Debugger.SourceLocation

If specified, later functions will be excluded.

Analysis.addLocation #

Apply the analysis to every point where a source location executes.

parameters

analysisId: AnalysisId

Associated analysis.
location: Debugger.Location

Location to apply the analysis to.
onStackFrame: Recording.ExecutionPoint

If specified, the analysis will only be applied to matching points which execute while this point's frame is on the stack.

Analysis.addPoints #

Apply the analysis to a specific set of points.

parameters

analysisId: AnalysisId

Associated analysis.
points: array[ Recording.ExecutionPoint ]

Points to apply the analysis to.

Analysis.addRandomPoints #

Apply the analysis to a random selection of points.

parameters

analysisId: AnalysisId

Associated analysis.
numPoints: integer

Maximum number of points to apply the analysis to.

Analysis.createAnalysis #

Start specifying a new analysis.

parameters

mapper: string

Body of the mapper function. The mapper function takes two arguments: input is a MapInput object, and sendCommand is a function that can be passed a command name and parameters (in that order) and synchronously returns the command result. Only methods from the Pause domain may be used with sendCommand. The mapper function must return an array of AnalysisEntry objects.
name: string

A logical name for the analysis. Does not have any constraints aside from being a valid string. May be omitted.
priority: string

A priority for the analysis. The priority must be one of the strings "user" (indicating that the analysis was user-created), or "app" (indicating that the analysis was automatically created by the frontend app). The priority may be omitted, in which case "user" priority is assumed.
reducer: string

Body of the reducer function. The reducer function takes two arguments: key is an AnalysisKey, and values is an array of AnalysisValue. All the values were associated with the key by an earlier call to mapper or reducer. The reducer function must return an AnalysisValue, which summarizes all the input values and will be associated with key for analysisResult events or further calls to the reducer. The reducer may be omitted if no reduction phase is needed.
effectful: boolean

Whether effectful commands in the Pause domain might be sent by the mapper function. An analysis which does not use effectful commands will run more efficiently. See the Pause domain for which commands are effectful.
range: Recording.PointRange

Any subrange of the recording which the analysis will run in.

Return Object

analysisId: AnalysisId

ID of the resulting analysis.

Analysis.findAnalysisPoints #

Find the set of execution points at which an analysis will run. After this is called, analysisPoints events will be emitted as the points are found. Does not return until events for all points have been emitted. Points will not be emitted for parts of the recording that are unloaded, see Session.listenForLoadChanges and Session.loadRegion.

NOTE: Changes to the focus window may cause pending commands to fail.

parameters

analysisId: AnalysisId

Analysis to find points for.

Analysis.releaseAnalysis #

Release an analysis and its server side resources. If the analysis is running, it will be canceled, preventing further analysisResult and analysisError events from being emitted.

parameters

analysisId: AnalysisId

Analysis to release.

Analysis.runAnalysis #

Run the analysis. After this is called, analysisResult and/or analysisError events will be emitted as results are gathered. Does not return until the analysis has finished and all events have been emitted. Results will not be gathered in parts of the recording that are unloaded, see Session.listenForLoadChanges and Session.requestFocusRange.

NOTE: Changes to the focus window may cause pending commands to fail.

parameters

analysisId: AnalysisId

Analysis to run.

Events

Analysis.analysisError #

Describes an error that occurred when running an analysis mapper or reducer function. This will not be emitted for every error, but if there was any error then at least one event will be emitted.

parameters

analysisId: AnalysisId

Associated analysis.
error: string

Description of the error.

Analysis.analysisPoints #

Describes some points at which an analysis will run.

parameters

analysisId: AnalysisId

Associated analysis.
points: array[ Debugger.PointDescription ]

Some points at which the analysis will run.

Analysis.analysisResult #

Describes some results of an analysis.

parameters

analysisId: AnalysisId

Associated analysis.
results: array[ AnalysisEntry ]

Results for different keys. If a reducer was specified, a given key can only appear once in the results emitted for the analysis.

Types

Analysis.AnalysisEntry #

A key/value pair produced by an analysis.

Type: object

properties

key: AnalysisKey
value: AnalysisValue

Analysis.AnalysisId #

Unique identifier for an analysis.

Type: string

Analysis.AnalysisKey #

Key for an analysis result. This can be any JSON value. Keys are equivalent if they are structurally equivalent: they have the same contents, though object keys may be ordered differently when stringified.

Type: any

Analysis.AnalysisValue #

Value for an analysis result. This can be any JSON value.

Type: any

Analysis.MapInput #

Input to the mapper function.

Type: Recording.TimeStampedPoint

properties

pauseId: Pause.PauseId

Pause ID created for the current execution point.