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 atbody
, otherwise look atmessage
-
body
: The "return value" of the command, only ifsuccess
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 requestedtoFrame
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 ifatReturn
is true -
debuggerFrame
: boolean -
arguments
:Array[{name, value}]
, value is a reference -
locals
: Same asarguments
-
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 theframe
request.
Additionally:
-
inlineRefs
: boolean, if trueobject
will be returned as a value
rather than as a reference, seescope
below.
Response
-
fromScope
: number, always 0 -
toScope
: number, always number of scopes -
totalScopes
: number of scopes -
scopes
: Array, seescope
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 trueobject
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 callednumber
above. -
frameIndex
: The same thing calledframeNumber
above. -
type
: Scope type, seeframe
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 asline
/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 theframe
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
: Includesource
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 intoids
.
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 bitmaksbit 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 asstack_modified
-
stepin_recommended
: true ifstack_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 ofname
andvalue
.
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 ofname
andvalue
as above.
If noflags
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:
Page in the v8 wiki: