V8 Debugger Protocol

This document describes the message based protocol exposed by V8. It's a very simple text-based protocol. As with HTTP there's a strict definition of line breaks: They MUST be "\r\n". Every message frame consists of a headers and a body part:

Header-A: Some-Value\r\n
Content-Length: 9\r\n
\r\n
{"seq":1}

Each frame MUST have a Content-Length headers. The header value MUST be the byte length of the body section. The next message starts immediately after the last byte of the body. The body is generally JSON encoded, see frame body below for the format.

When connecting a special, body-less message is sent by V8. The following example is from connecting to a node.js instance:

Type: connect\r\n
V8-Version: 3.14.5.9\r\n
Protocol-Version: 1\r\n
Embedding-Host: node v0.10.26\r\n
Content-Length: 0\r\n
\r\n

Frame Body

Each message body is a JSON object with the following properties:

seq: Identifier of this message. This is used to map responses to the proper request.
type: Either "request", "response", or "event"

Request Message

These are sent by the debug client to v8. Request messages have two additional properties:

command: The command that is invoked
arguments: A object with named arguments, optional

Available commands are documented below.

Example

{"seq":117,"type":"request","command":"continue"}

Response Message

These are sent to the debug client by v8. Response message have the following additional properties:

request_seq: The request this is the response to
command: The original command
success: If true, look at body, otherwise look at message
body: The "return value" of the command, only if success is true
message: Error message for failed commands
running: false if the vm is suspended, true otherwise
refs: Array of referenced values in the body

The type of body to expect is documented below, in the section request/response pairs.

Example: Successful response

{ "seq":67,
  "type":"response",
  "request_seq":117,
  "command":"continue",
  "success":true,
  "running": true }

Example: Successful response, returning data

{ "seq":67,
  "type":"response",
  "request_seq":117,
  "command":"scope",
  "success":true,
  "running": true,
  "body": { "index":0, "frameIndex":0 } }

Example: Failing response

{ "seq":67,
  "type":"response",
  "request_seq":117,
  "command":"frame",
  "success":false,
  "running": true,
  "message": "Missing arguments" }

Example: What is `refs`?

Important to note: There's no guarantee that everything referenced inside of refs will itself resolve. The ref properties denote references to mirror objects. Mirror objects are identified by their handle. refs contains an array of serialized mirror objects.

[ { handle: 4,
    type: 'function',
    className: 'Function',
    constructorFunction: { ref: 8 },
    protoObject: { ref: 9 },
    prototypeObject: { ref: 5 },
    name: 'Error',
    inferredName: '',
    resolved: true,
    source: 'function Error() { [native code] }',
    scopes: [],
    properties: 
     [ { name: 'length', attributes: 7, propertyType: 3, ref: 10 },
       { name: 'name', attributes: 7, propertyType: 3, ref: 11 } ],
    text: 'function Error() { [native code] }' },
  { handle: 6, type: 'undefined', text: 'undefined' },
  { handle: 7,
    type: 'string',
    value: 'err message',
    length: 11,
    text: 'err message' } ]

Event Message

Sent by v8 to the debug client. These messages look similar to response messages in that they also contain body and refs. Additionally:

event: Type of event

You can find a list of available events below.

Request/response pairs

The name of the command is followed by the name of function in src/debug-debugger.js that handles the command. Most filenames in this section reference the v8 codebase. Other important files are mirror-debugger.js and messages.js for serialization. Implementation details of macros can be found in runtime.cc.

Request `continue` - `continueRequest_`

The request continue is a request from the debugger to start the VM running again. As part of the continue request the debugger can specify if it wants the VM to perform a single step action.

In the response the property running will always be true as the VM will be running after executing the continue command. If a single step action is requested the VM will respond with a break event after running the step.

Warning: Sometimes the non-presence of arguments is not the same as an empty arguments object. Also even though it looks like the handler for continue doesn't do anything when no arguments are passed in, the fact that it is setting response.running to true will magically resume execution.

Arguments

When no arguments are provided, this command will just resume execution.

For step-based actions, pass the following arguments:

stepaction: One of the actions listed below, string, required (the default value is ignored)
stepcount: How many steps to take, uint, optional, default: 1

Available step actions (taken from src/debug.h)

out: Step out of the current function. StepOut = 0
next: Step to the next statement in the current function. StepNext = 1
in: Step into new functions invoked or the next statement in the current function. StepIn = 2
min: Perform a minimum step in the current function. StepMin = 3

StepInMin does not seem to be supported by the debugger protocol.

Response

Empty response

Example: Just resume execution

{"seq":117,"type":"request","command":"continue"}

Example: Step forward 5 statements

{ "seq":117,"type":"request","command":"continue",
  "arguments": { "stepaction": "next", "stepcount": 5 } }

Request `break` - `breakRequest_`

Seems to be doing nothing. Quote:

Ignore as break command does not do anything when broken.

Request `setbreakpoint` - `setBreakPointRequest_`

The request setbreakpoint creates a new break point. This request can be used to set both function and script break points. A function break point sets a break point in an existing function whereas a script break point sets a break point in a named script. A script break point can be set even if the named script is not found.

The result of the setbreakpoint request is a response with the number of the newly created break point. This break point number is used in the changebreakpoint and clearbreakpoint requests.

Arguments

type: Type of breakpoint to create, see below (string)
target: Script or function to break at (string)
line/column: Position for script breakpoints (uint)
enabled: Starts off enabled, default: true
condition: Expression that guards the breakpoint (string)
ignoreCount: uint, default: 0
groupId: Script breakpoints only, allows to clear multiple breakpoints at once, uint.

Known breakpoint types and what target should be:

function: target evaluates to a function in global scope
handle: target is the (stringified) handle of a function
script: target is the name of a script
scriptId: target is the id of some already compiled script
scriptRegExp: target matches the name of a script

Response

type: "scriptId", "scriptName", "scriptRegExp", or "function"
breakpoint: Breakpoint id, number
actual_locations: Array of locations where the breakpoint will fire. Will have one element for function breakpoints, may have multiple locations for script breakpoints. Every entry consists of {scriptId, line, columns}.
line/column: Location of breakpoint, script breakpoint only
script_id: Only for scriptId breakpoints
script_name: Only for scriptName breakpoints
script_regexp: Regex (as string), only for scriptRegExp breakpoints

Examples

{"seq":117,"type":"request","command":"setbreakpoint","arguments":{"type":"function","target":"f"}}
{"seq":118,"type":"request","command":"setbreakpoint","arguments":{"type":"script","target":"test.js","line":100}}
{"seq":119,"type":"request","command":"setbreakpoint","arguments":{"type":"function","target":"f","condition":"i > 7"}}

Request `setexceptionbreak` - `setExceptionBreakRequest_`

The request setexceptionbreak is a request to enable/disable breaks on all / uncaught exceptions. If the "enabled" argument is not specify, the debuggee will toggle the state of the specified break type.

Arguments

type: Either "all" or "uncaught", required
enabled: Defaults to the opposite of whatever the current state is

Response

type and enabled. If enabled wasn't passed in, the response can be used to detect the current status.

Examples

{"seq":117,"type":"request","command":"setexceptionbreak","arguments":{"type":"all"}}
{"seq":118,"type":"request","command":" setexceptionbreak","arguments":{"type":"all","enabled":false}}
{"seq":119,"type":"request","command":" setexceptionbreak","arguments":{"type":"uncaught","enabled":true}}

Request `changebreakpoint` - `changeBreakPointRequest_`

The request changebreakpoint changes the status of a break point.

Arguments

breakpoint: Breakpoint id, number
enabled: Optional, enable or disable the breakpoint
condition: Optional, change the condition
ignoreCount: Optional, reset the ignore count

Response

Empty response

Request `clearbreakpoint` - `clearBreakPointRequest_`

The request clearbreakpoint clears a break point.

Arguments

breakpoint: Breakpoint id, number

Response

breakpoint: Breakpoint id, number

Examples

{"seq":117,"type":"request","command":"clearbreakpoint","arguments":{"type":"function","breakpoint":1}}
{"seq":118,"type":"request","command":"clearbreakpoint","arguments":{"type":"script","breakpoint":2}}

Request `clearbreakpointgroup` - `clearBreakPointGroupRequest_`

Arguments

groupId: Breakpoint group id, number

Response

breakpoints: Array of cleared breakpoint ids

Request `listbreakpoints` - `listBreakpointsRequest_`

The request listbreakpoints is used to get information on breakpoints that may have been set by the debugger.

This seems to only list script break points.

Arguments

No arguments

Response

breakpoints: Array of breakpoints, see below
breakOnExceptions: Current state of "all"
breakOnUncaughtExceptions: Current state of "uncaught"

Breakpoint descriptions contain the following fields:

type: "scriptId", "scriptName", "scriptRegExp", or "function"
number: Breakpoint id, number
line/column: Position in file
groupId: Breakpoint group id
hit_count: How often the breakpoint was hit already
active: If the breakpoint is enabled
condition: Condition expression
ignoreCount: Remaining ignore count. Will update whenever the breakpoint is ignored.
actual_locations: See above, {scriptId, line, column}
script_id: Only for scriptId breakpoints
script_name: Only for scriptName breakpoints
script_regexp: Regex (as string), only for scriptRegExp breakpoints

Examples

{"seq":117,"type":"request","command":"listbreakpoints"}

Request `disconnect` - `disconnectRequest_`

The request disconnect is used to detach the remote debugger from the debuggee. This will trigger the debuggee to disable all active breakpoints and resumes execution if the debuggee was previously stopped at a break.

Disable all breakpoints and continue.

Arguments

All arguments that are valid for continue will work though anything but no arguments could be pretty confusing.

Response

Empty response

Examples

{"seq":117,"type":"request","command":"disconnect"}

Request `backtrace` - `backtraceRequest_`

The request backtrace returns a backtrace (or stacktrace) from the current execution state. When issuing a request a range of frames can be supplied. The top frame is frame number 0. If no frame range is supplied data for 10 frames will be returned.

Arguments

fromFrame: Index of first frame to return
toFrame: Exclusive end of range
bottom: Boolean, set to true if the bottom of the stack is requested

Response

fromFrame: First frame returned
toFrame: Actual last frame returned, might be less than requested toFrame when less frames are available.
totalFrames: Number of frames currently available
frames: Array of frames

For the properties of each frame, see the frame request below.

Examples

{"seq":117,"type":"request","command":"backtrace"}
{"seq":118,"type":"request","command":"backtrace","arguments":{"toFrame":2}}
{"seq":119,"type":"request","command":"backtrace","arguments":{"fromFrame":0,"toFrame":9}}

Request `frame` - `frameRequest_`

The request frame selects a new selected frame and returns information for that. If no frame number is specified the selected frame is returned.

Arguments

number: Optional, the frame to select

Response

index: number
receiver: reference
func: reference
script: reference
constructCall: boolean
atReturn: boolean
returnValue: reference, only if atReturn is true
debuggerFrame: boolean
arguments: Array[{name, value}], value is a reference
locals: Same as arguments
scopes: Array[{type, index}], both are numbers

Valid scope types:

var ScopeType = { Global: 0,
                  Local: 1,
                  With: 2,
                  Closure: 3,
                  Catch: 4,
                  Block: 5,
                  Script: 6 };

Reference: JSONProtocolSerializer.serializeFrame_

Examples

{"seq":117,"type":"request","command":"frame"}
{"seq":118,"type":"request","command":"frame","arguments":{"number":1}}

Request `scopes` - `scopesRequest_`

The request scopes returns all the scopes for a given frame. If no frame number is specified the selected frame is returned.

Arguments

A "scope holder". This is either a stack frame or a function. From resolveScopeHolder_:

Gets scope host object from request. It is either a function ('functionHandle' argument must be specified) or a stack frame ('frameNumber' may be specified and the current frame is taken by default).

For function scopes:

functionHandle: number, retrieves function from mirror cache

For stack frame scopes:

frameNumber: number, has to be a valid frame index. Defaults to currently selected stack frame if omitted. Stack frames are selected via the frame request.

Additionally:

inlineRefs: boolean, if true object will be returned as a value rather than as a reference, see scope below.

Response

fromScope: number, always 0
toScope: number, always number of scopes
totalScopes: number of scopes
scopes: Array, see scope below for properties

Examples

{"seq":117,"type":"request","command":"scopes"}
{"seq":118,"type":"request","command":"scopes","arguments":{"frameNumber":1}}

Request `scope` - `scopeRequest_`

The request scope returns information on a given scope for a given frame. If no frame number is specified the selected frame is used.

Arguments

A "scope holder" (see scopes) plus:

number: A valid scope index, defaults to 0 (top scope)
inlineRefs: boolean, if true object will be returned as a value rather than as a reference

Response

index: index of this scope in the scope chain. Index 0 is the top scope and the global scope will always have the highest index for a frame (from v8 wiki) Confusingly the same value that is called number above.
frameIndex: The same thing called frameNumber above.
type: Scope type, see frame above
object: reference or value, an object representing the scope

The object part depends on the special inlineRefs argument.

`object` as reference

Will have just one property, ref, which is the mirror's handle. The object itself will be added to the refs part of the response. Every object added will later be serialized via serializeReferencedObjects. The serialization will exclude details which means that actual property values won't be included. In other words: For scope requests this is a poor fit.

`object` as value

This described the general structure of something serialized via serialize_(obj, false, true) - not as reference, with details. You can assume that a scope object should be an object.

type: string, type of mirror, see below for possible values. This is the only property for 'null' and 'undefined'.
handle: number, handle of the serialized mirror

For 'boolean', 'number', 'string':

value: May be truncated for strings.
length: Only for strings, total length of string
fromIndex/toIndex: 0/length of truncated string. Not present if the string was returned in full.

For 'object', 'function', 'regexp', 'error' (see serializeObject_):

className: string, name of the class
constructorFunction: reference
protoObject: reference
prototypeObject: reference
namedInterceptor: boolean
indexedInterceptor: boolean
properties: Array of property descriptors
internalProperties: Array of property descriptors

All references are serialized via serializeReferenceWithDisplayData_. See the properties section below.

For 'function only:

name: Name of the function
inferredName: "Nice" name of the function, not always available
resolved: boolean, source is available
source: The source of the function
script: Reference to the script where the function is defined
scriptId: Id of the script where the function is defined`
line/column: Position of the function definition in the script
position: Seems to be the same as line/column

If the object is a date object:

value: ?

Properties

Each property is serialized based on inlineRefs. The serialization is handled by serializeProperty_. Property descriptors always have a name property.

When inlineRefs is enabled then each descripor has a value property. It is filled using serializeReferenceWithDisplayData_:

ref: Handle of the mirror object
type: See below for possible types
value: For 'undefined', 'null', 'boolean', 'number', 'string', 'error', 'regexp'. For 'string' the value will be truncated. For 'error' the value will be ?.
name: For 'function' - name of the function
inferredName: For 'function' - nice name of the function
scriptId: For 'function' - Script where the function was defined
className: For 'object' - name of the class

Without inlineRefs, the property descriptor will only contain meta data:

ref: The property value's handle.
attributes: Signals if property is frozen/readOnly/etc..
propertyType: Only if it isn't a "normal" property.

Possible values for property type are:

// from mirror-debugger.js
PropertyType.Normal                  = 0;
PropertyType.Field                   = 1;
PropertyType.Constant                = 2;
PropertyType.Callbacks               = 3;
PropertyType.Handler                 = 4;
PropertyType.Interceptor             = 5;
PropertyType.Transition              = 6;
PropertyType.Nonexistent             = 7;

Values for `type`

// from mirror-debugger.js
var UNDEFINED_TYPE = 'undefined';
var NULL_TYPE = 'null';
var BOOLEAN_TYPE = 'boolean';
var NUMBER_TYPE = 'number';
var STRING_TYPE = 'string';
var OBJECT_TYPE = 'object';
var FUNCTION_TYPE = 'function';
var REGEXP_TYPE = 'regexp';
var ERROR_TYPE = 'error';
// ignore everything below, won't be retured
var PROPERTY_TYPE = 'property';
var INTERNAL_PROPERTY_TYPE = 'internalProperty';
var FRAME_TYPE = 'frame';
var SCRIPT_TYPE = 'script';
var CONTEXT_TYPE = 'context';
var SCOPE_TYPE = 'scope';

Examples

{"seq":117,"type":"request","command":"scope"}
{"seq":118,"type":"request","command":"scope","arguments":{"frameNumber":1,"number":1}}

Request `setVariableValue` - `setVariableValueRequest_`

Arguments

scope: Scope holder & number
name: Name of the variable to set
newValue: The value to set the variable to

The scope will be resolved via resolveScopeHolder_. It has to have a property number (the scope index). It may have a functionHandle property. If it has no functionHandle, it's considered a frame-based scope. In that case an optional frameNumber can be provided.

The newValue will be resolved via resolveValue_. The following kinds of values are supported:

handle: A mirror's handle
stringDescription/type: The description will be parsed. Supported types are 'number', 'string', and 'boolean'.
value: Just a value
type: Possible values are 'undefined' or 'null'

Response

newValue: A mirror object for the new value

Request `evaluate` - `evaluateRequest_`

The request evaluate is used to evaluate an expression. Optional argument additional_context specifies handles that will be visible from the expression under corresponding names

Arguments

expression:
frame:
global:
disable_break:
additional_context:

Response

The result of evaluating the expression. See scope above for what it looks like.

Examples

{"seq":117,"type":"request","command":"evaluate","arguments":{"expression":"1+2"}}
{"seq":118,"type":"request","command":"evaluate","arguments":{"expression":"a()","frame":3,"disable_break":false}}
{"seq":119,"type":"request","command":"evaluate","arguments":{"expression":"[o.a,o.b,o.c]","global":true,"disable_break":true}}
{"seq":120,"type":"request","command":"evaluate","arguments":{"expression":"obj.toString()", "additional_context": [{ "name":"obj","handle":25 }] }}

Request `lookup` - `lookupRequest_`

The request lookup is used to lookup objects based on their handle.

Arguments

handles: Array of mirror handles (numbers)
includeSource: Include source of scripts (if mirrors are scripts)

Response

Mirror objects indexed by their handle. See scope for how each entry looks like.

Examples

{"seq":117,"type":"request","command":"lookup","arguments":{"handles":[1]}}
{"seq":118,"type":"request","command":"lookup","arguments":{"handles":[7,12]}}

Request `references` - `referencesRequest_`

Arguments

type: Either "referencedBy" or "constructedBy"
handle: Object to find references for

Response

Array of referenced objects

For referencedBy:

Find all objects with direct references to this object.

For constructedBy:

Returns objects constructed by this function.

Request `source` - `sourceRequest_`

The request source retrieves source code for a frame. It returns a number of source lines running from the fromLine to but not including the toLine, that is the interval is open on the "to" end. For example, requesting source from line 2 to 4 returns two lines (2 and 3). Also note that the line numbers are 0 based: the first line is line 0.

Arguments

frame: Index of the frame, default: selected frame. Frames are selected with the frame request.
fromLine: First line to return, defaults to first line
toLine: First line not to return, defaults to the end of the script

Response

source: The actual source code
fromLine: Actual first line returned
toLine: Actual first line not returned
fromPosition: First character index returned
toPosition: First character index not returned
totalLines: Total number of lines in the file

Examples

{"seq":117,"type":"request","command":"source","arguments":{"fromLine":10,"toLine":20}}
{"seq":118,"type":"request","command":"source","arguments":{"frame":2,"fromLine":10,"toLine":20}}

Request `scripts` - `scriptsRequest_`

The request scripts retrieves active scripts from the VM. An active script is source code from which there is still live objects in the VM. This request will always force a full garbage collection in the VM.

Arguments

types: Bitmask of script types to retrieve. Defaults to "normal" only.
ids: Filter by script ids, invalid ids are just ignored. Defaults to returning all scripts.
includeSource: Include source in the response, defaults to false
filter: If this looks like a number, only scripts with this script id will be returned. This might or might not be the same as just passing one id into ids. If it's a string, it will filter scripts by if the name contains the filter.

Script types are:

0: Native scripts, in bitmask: 1 << 0 = 1
1: Extension scripts, in bitmask: bit 1 = 1 << 1 = 2
2: Normal scripts, in bitmaks bit 2 = 1 << 2 = 4

Response

Array of script mirror objects. Descriptions where partially taken from the v8 wiki.

name: name of the script
id: id of the script
lineOffset: line offset within the containing resource
columnOffset: column offset within the containing resource
lineCount: number of lines in the script
data: optional data object added through the API
source: source of the script if includeSource was specified in the request
sourceStart: first 80 characters of the script if includeSource was not specified in the request
sourceLength: total length of the script in characters
scriptType: script type (see request for values)
compilationType: How was this script compiled. 0 if script was compiled through the API 1 if script was compiled through eval
evalFromScript: if "compilationType" is 1 this is the script from where eval was called
evalFromLocation: {line,column} if "compilationType" is 1 this is the position in the script from where eval was called
evalFromFunctionName: If "compilationType" is 1 this is the function name from where eval was called

Examples

{"seq":117,"type":"request","command":"scripts"}
{"seq":118,"type":"request","command":"scripts","arguments":{"types":7}}

Request `threads` - `threadsRequest_`

Arguments

No arguments

Response

totalThreads: Number of threads
thread_info.id: Id of the thread, number
thread_info.current: If the thread is the current one, boolean

Request `suspend` - `suspendRequest_`

No arguments, no response. Pauses execution. The reverse of calling continue without arguments.

Request `version` - `versionRequest_`

The request version reports version of the running V8.

Response

V8Version: The version of v8 the process is running

Examples

{"seq":1,"type":"request","command":"version"}
{"seq":134,"request_seq":1,"type":"response","command":"version","success":true,"body":{"V8Version":"1.3.19 (candidate)"},"refs":[],"running":false}

Request `changelive` - `changeLiveRequest_`

The juicy parts can be found in liveedit-debugger.js.

Arguments

script_id: Id of the script to change
preview_only: Do a dry run without actually changing the source
new_source: The new source code for the script

Response

change_log: ?
result.stack_modified: Changes affect one of the current stack frames
result.change_tree: Tree of changes
result.textual_diff.old_len: Length of old source code
result.textual_diff.new_len: Length of new source code
result.textual_diff.chunks: Changed chunks
result.updated: True if any change was made
result.created_script_name: Sometimes the diff algorithm needs to create a copy of the old script.
result.stack_update_needs_step_in: Same as stack_modified
stepin_recommended: true if stack_update_needs_step_in and the VM isn't currently paused. Will not be set for preview requests.

Request `restartframe` - `restartFrameRequest_`

The juicy parts can be found in liveedit-debugger.js.

Warning: This is one of the few functions where empty arguments are required to be passed in as {} instead of not sending anything.

Arguments

frame: Valid stack frame or undefined for the selected frame.

Response

result.stack_update_needs_step_in: Always true

Request `flags` - `debuggerFlagsRequest_`

Warning: This is one of the few functions where empty arguments are required to be passed in as {} instead of not sending anything.

Known flags:

breakPointsActive
breakOnCaughtException
breakOnUncaughtException

Arguments

flags: Pair of name and value. The value is optional, if it is provided the flag will be updated. Filters which flags are returned. If omitted, all flags are returned. Invalid or unknown flags are gracefully ignored.

Response

flags: Array of flags, same pair of name and value as above. If no flags were passed in, this will return all current flag values.

Request `v8flags` - `v8FlagsRequest_`

The request v8flags is a request to apply the specified v8 flags (analogous to how they are specified on the command line).

Warning: This is one of the few functions where empty arguments are required to be passed in as {} instead of not sending anything.

Arguments

flags: A string with command line flags, defaults to empty string.

Response

No response

Examples

{"seq":117,"type":"request","command":"v8flags","arguments":{"flags":"--trace_gc —-always_compact"}}
{"seq":118,"type":"request","command":" v8flags","arguments":{"flags":"--notrace_gc"}}

Request `gc` - `gcRequest_`

The request gc is a request to run the garbage collector in the debuggee. In response, the debuggee will run the specified GC type.

Warning: This is one of the few functions where empty arguments are required to be passed in as {} instead of not sending anything.

Arguments

type: Defaults to "all"

As for available types, to quote runtime.cc:

Presently, it only does a full GC.

Response

before: Heap usage before, integer
after: Heap usage after, integer

Examples

{"seq":117,"type":"request","command":"gc","arguments":{"type":"all"}}

Events

Each event name is followed by the name of the event class in debug-debugger.js. The number in front is the v8-internal enum value of the event. The representation of the event body is determined by the method toJSONProtocol of the event class.

All examples omit the wrapping message and only show the body. We'll also show the parsed body - JSON with slightly less quotes. For completeness' sake here one relatively complete event frame:

Content-Length: 78\r\n
\r\n
{"seq":42,"type":"event","event":"beforeCompile","body":{"script":{"id":"1"}}}

1: Event `break` - `BreakEvent`

Event Body

invocationText: Text representation of the top stack frame
script: Script in which the break occured
sourceLineText: Source code of the line where execution stopped
sourceLine/sourceColumn: Position in the script
breakpoints: Array of ids of breakpoints that caused the break

Examples

{ invocationText: '#<Object>.[anonymous](exports=#<Object>, require=function require(path) {\n    return self.require(path);\n  }, module=#<Module>, __filename=/full/path/to/test/buggers/breakpoint.js, __dirname=/full/path/to/test/buggers)',
  sourceLine: 16,
  sourceColumn: 2,
  sourceLineText: '})();',
  script: 
   { id: 46,
     name: '/full/path/to/test/buggers/breakpoint.js',
     lineOffset: 0,
     columnOffset: 0,
     lineCount: 19 },
  breakpoints: [ 1 ] }

2: Event `exception` - `ExceptionEvent`

Event Body

invocationText: Text representation of the top stack frame
script: Script in which the break occured
sourceLineText: Source code of the line where execution stopped
sourceLine/sourceColumn: Position in the script. sourceLine may be -1 if there's no valid stack frame.
uncaught: true if this was an uncaught exception
exception: The exception object

Examples

{ uncaught: false,
  exception: 
   { handle: 0,
     type: 'error',
     className: 'Error',
     constructorFunction: { ref: 4 },
     protoObject: { ref: 5 },
     prototypeObject: { ref: 6 },
     properties: [
      { name: 'stack', attributes: 2, propertyType: 3, ref: 6 },
      { name: 'arguments', attributes: 2, propertyType: 1, ref: 6 },
      { name: 'type', attributes: 2, propertyType: 1, ref: 6 },
      { name: 'message', attributes: 2, propertyType: 1, ref: 7 } ],
     text: 'Error: err message' },
  sourceLine: 3,
  sourceColumn: 10,
  sourceLineText: '    throw new Error(\'err message\');',
  script: 
   { id: 46,
     name: '/full/path/to/test/buggers/throws.js',
     lineOffset: 0,
     columnOffset: 0,
     lineCount: 12 } }

3: Event `?` - `NewFunctionEvent`

Not exposed in any obvious way

4: Event `beforeCompile` - `CompileEvent`

Event Body

See: afterCompile

5: Event `afterCompile` - `CompileEvent`

script: The script that was compiled

Examples

{ script: 
   { handle: 1,
     type: 'script',
     name: 'node.js',
     id: 30,
     lineOffset: 0,
     columnOffset: 0,
     lineCount: 903,
     sourceStart: '// Copyright Joyent, Inc. and other Node contributors.\n//\n// Permission is hereb',
     sourceLength: 28135,
     scriptType: 2,
     compilationType: 0,
     context: { ref: 0 },
     text: 'node.js (lines: 903)' } }

6: Event `scriptCollected` - `ScriptCollectedEvent`

Emitted when a script is no longer referenced and was collected.

Event Body

See: afterCompile

7: Event ?

BreakForCommand, defined in v8-debug.h

Response object serialization

For now see scope

// From mirror-debugger.js
// Mirror hierarchy:
//   - Mirror
//     - ValueMirror
//       - UndefinedMirror
//       - NullMirror
//       - NumberMirror
//       - StringMirror
//       - ObjectMirror
//         - FunctionMirror
//           - UnresolvedFunctionMirror
//         - ArrayMirror
//         - DateMirror
//         - RegExpMirror
//         - ErrorMirror
//     - PropertyMirror
//     - InternalPropertyMirror
//     - FrameMirror
//     - ScriptMirror

Important links

Original author in the v8 wiki:

https://code.google.com/u/mikhail.naganov/

Page in the v8 wiki:

https://code.google.com/p/v8/wiki/DebuggerProtocol

Files

PROTOCOL.md

Latest commit

History

PROTOCOL.md

File metadata and controls

V8 Debugger Protocol

Frame Body

Request Message

Example

Response Message

Example: Successful response

Example: Successful response, returning data

Example: Failing response

Example: What is refs?

Event Message

Request/response pairs

Request continue - continueRequest_

Arguments

Response

Example: Just resume execution

Example: Step forward 5 statements

Request break - breakRequest_

Request setbreakpoint - setBreakPointRequest_

Arguments

Response

Examples

Request setexceptionbreak - setExceptionBreakRequest_

Arguments

Response

Examples

Request changebreakpoint - changeBreakPointRequest_

Arguments

Response

Request clearbreakpoint - clearBreakPointRequest_

Arguments

Response

Examples

Request clearbreakpointgroup - clearBreakPointGroupRequest_

Arguments

Response

Request listbreakpoints - listBreakpointsRequest_

Arguments

Response

Examples

Request disconnect - disconnectRequest_

Arguments

Response

Examples

Request backtrace - backtraceRequest_

Arguments

Response

Examples

Request frame - frameRequest_

Arguments

Response

Examples

Request scopes - scopesRequest_

Arguments

Response

Examples

Request scope - scopeRequest_

Arguments

Response

object as reference

object as value

Properties

Values for type

Examples

Request setVariableValue - setVariableValueRequest_

Arguments

Response

Request evaluate - evaluateRequest_

Arguments

Response

Examples

Request lookup - lookupRequest_

Arguments

Response

Examples

Example: What is `refs`?

Request `continue` - `continueRequest_`

Request `break` - `breakRequest_`

Request `setbreakpoint` - `setBreakPointRequest_`

Request `setexceptionbreak` - `setExceptionBreakRequest_`

Request `changebreakpoint` - `changeBreakPointRequest_`

Request `clearbreakpoint` - `clearBreakPointRequest_`

Request `clearbreakpointgroup` - `clearBreakPointGroupRequest_`

Request `listbreakpoints` - `listBreakpointsRequest_`

Request `disconnect` - `disconnectRequest_`

Request `backtrace` - `backtraceRequest_`

Request `frame` - `frameRequest_`

Request `scopes` - `scopesRequest_`

Request `scope` - `scopeRequest_`

`object` as reference

`object` as value

Values for `type`

Request `setVariableValue` - `setVariableValueRequest_`

Request `evaluate` - `evaluateRequest_`

Request `lookup` - `lookupRequest_`

Request `references` - `referencesRequest_`

Request `source` - `sourceRequest_`

Request `scripts` - `scriptsRequest_`

Request `threads` - `threadsRequest_`

Request `suspend` - `suspendRequest_`

Request `version` - `versionRequest_`

Request `changelive` - `changeLiveRequest_`

Request `restartframe` - `restartFrameRequest_`

Request `flags` - `debuggerFlagsRequest_`

Request `v8flags` - `v8FlagsRequest_`

Request `gc` - `gcRequest_`

1: Event `break` - `BreakEvent`

2: Event `exception` - `ExceptionEvent`

3: Event `?` - `NewFunctionEvent`

4: Event `beforeCompile` - `CompileEvent`

5: Event `afterCompile` - `CompileEvent`

6: Event `scriptCollected` - `ScriptCollectedEvent`