The message based API is no longer maintained. Please ask in [email protected] if you want to attach a debugger to the run-time.
Introduction
V8 has support for debugging the JavaScript code running in it. There are two API's for this a function based API using JavaScript objects and a message based API using a JSON based protocol. The function based API can be used by an in-process debugger agent, whereas the message based API can be used out of process as well.
The debugger protocol is based on JSON). Each protocol packet is defined in terms of JSON and is transmitted as a string value. All packets have two basic elements seq and type.
{ "seq" : ,
"type" : ,
...
}
The element seq holds the sequence number of the packet. And element type is the type of the packet. The type is a string value with one of the following values "request", "response" or "event".
A "request" packet has the following structure:
{ "seq" : ,
"type" : "request",
"command" :
"arguments" : ...
}
A "response" packet has the following structure. If success is true body will contain the response data. If success is false message will contain an error message.
{ "seq" : ,
"type" : "response",
"request_seq" : ,
"command" :
"body" : ...
"running" :
"success" :
"message" :
}
An "event" packet has the following structure:
{ "seq" : ,
"type" : "event",
"event" :
body : ...
}
Request/response pairs
Request continue
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.
{ "seq" : ,
"type" : "request",
"command" : "continue",
"arguments" : { "stepaction" : <"in", "next" or "out">,
"stepcount" :
}
}
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.
{ "seq" : ,
"type" : "response",
"request_seq" : ,
"command" : "continue",
"running" : true
"success" : true
}
Here are a couple of examples.
{"seq":117,"type":"request","command":"continue"}
{"seq":118,"type":"request","command":"continue","arguments":{"stepaction":"out"}}
{"seq":119,"type":"request","command":"continue","arguments":{"stepaction":"next","stepcount":5}}
Request evaluate
The request evaluate is used to evaluate an expression. The body of the result is as described in response object serialization below.
{ "seq" : ,
"type" : "request",
"command" : "evaluate",
"arguments" : { "expression" : ,
"frame" : ,
"global" : ,
"disable_break" : ,
"additional_context" : [
{ "name" : , "handle" : },
{ "name" : , "handle" : },
...
]
}
}
Optional argument additional_context specifies handles that will be visible from the expression under corresponding names (see example below).
Response:
{ "seq" : ,
"type" : "response",
"request_seq" : ,
"command" : "evaluate",
"body" : ...
"running" :
"success" : true
}
Here are a couple of 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
The request lookup is used to lookup objects based on their handle. The individual array elements of the body of the result is as described in response object serialization below.
{ "seq" : ,
"type" : "request",
"command" : "lookup",
"arguments" : { "handles" : ,
"includeSource" : ,
}
}
Response:
{ "seq" : ,
"type" : "response",
"request_seq" : ,
"command" : "lookup",
"body" :
"running" :
"success" : true
}
Here are a couple of examples.
{"seq":117,"type":"request","command":"lookup","arguments":{"handles":"[1]"}}
{"seq":118,"type":"request","command":"lookup","arguments":{"handles":"[7,12]"}}
Request backtrace
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.
{ "seq" : ,
"type" : "request",
"command" : "backtrace",
"arguments" : { "fromFrame" :
"toFrame" :
"bottom" :
}
}
The response contains the frame data together with the actual frames returned and the toalt frame count.
{ "seq" : ,
"type" : "response",
"request_seq" : ,
"command" : "backtrace",
"body" : { "fromFrame" :
"toFrame" :
"totalFrames" :
"frames" :
}
"running" :
"success" : true
}
If there are no stack frames the result body only contains totalFrames with a value of 0. When an exception event is generated due to compilation failures it is possible that there are no stack frames.
Here are a couple of 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
The request frame selects a new selected frame and returns information for that. If no frame number is specified the selected frame is returned.
{ "seq" : ,
"type" : "request",
"command" : "frame",
"arguments" : { "number" :
}
}
Response:
{ "seq" : ,
"type" : "response",
"request_seq" : ,
"command" : "frame",
"body" : { "index" : ,
"receiver" : ,
"func" : ,
"script" :