ChromeDevToolsProtocol

The protocol is deprecated and its support is going to be finished. See below.

Google Chrome/Chromium browser is using WebKit Remote Debugging Protocol instead, see the main site for details.

Introduction

The existing V8 Debugger Protocol is not sufficient to provide Google Chrome, Chromium, or any other browser that supports the protocol, with the capability of remote debugging via TCP/IP sockets. The V8 Debugger protocol covers only JavaScript debugging operations, and only within a single V8 virtual machine (VM). In reality, there can be one or more separate V8 VMs inside a Google Chrome instance, residing in different renderer processes. Also, retrieving URLs loaded in the browser tabs, inspecting or modifying the DOM tree are not covered by JavaScript operations.

Because of these restrictions, the ChromeDevTools protocol has been created to enable the exchange of additional information between a remote debugger and the browser instance being debugged. The ChromeDevTools protocol can be used as a transport for other debugging-related protocols, including the existing V8 Debugger Protocol. The proposed protocol can be used as a transport for other debugging-related protocols, including the existing V8 Debugger Protocol.

A single subsystem that uses ChromeDevTools protocol as a transport for its own debugging-related protocol is called a "Tool". A V8 VM Debugger, a DOM debugger, or a Developer Tools Service are examples of a Tool.

How to start Google Chrome/Chromium

chrome --remote-debugging-port=<port>

How to attach from Debugger

A launch configuration named "Chromium JavaScript" should be created (see tutorial).

How to attach from SDK

Use the following create method:

org.chromium.sdk.BrowserFactory.getInstance().create(...)

Protocol Name

Protocol is called 'ChromeDevTools Protocol'. The name is pretty overloaded though. You can be sure that you are using this protocol if you are starting Google Chrome/Chromium with the following parameter: --remote-debugging-port=<port>

Compare with WebKit Remote Debugging Protocol.

Protocol Message Structure

For simplicity of parsing, and higher human readability, the generic protocol message structure follows that of an HTTP request/response message (barring the Starting line):

Header1
...
HeaderN
<empty line>
Content

where <empty line> represents a single pair of the \r\n (CR LF) characters.

A single header format is:

<HeaderName>:<HeaderValue>CRLF

Request/Response message headers

• Content-Length
• Tool
• Destination

Content-Length (required) - the total length of the Сontent field in bytes.

Tool (required) - a string specifying the Tool that will handle the message.

Destination (optional) - a string that identifies the concrete application-specific host object in whose context the message should be handled. For a V8 debugger it can be an identifier of a Google Chrome tab running JavaScript code, and for Developer Tools Service it can be absent altogether because the content pertains to the global Google Chrome context rather than some specific object contained in the browser (e.g. the content can contain a request for the supported version of the Developer Tools protocol.) "0" (zero) is an invalid host object identifier, reserved for specific protocol purposes.

Note: Tools may add other headers that they will extract while processing messages.

Content

The optional Content field value is unique to each command as well as the request/response message. For example, it can contain the V8 Debugger Protocol request/response JSON messages or some plain-text command for a simpler tool. The content must use the UTF8 charset. If this field is absent, the Content-Length header value must be 0.

Establishing the Debugger Connection

A remote debugger that supports the ChromeDevTools protocol, connects to a server socket opened by Google Chrome. A remote debugger sends a handshake message consisting of 23 ASCII characters,

ChromeDevToolsHandshakeCRLF

Google Chrome replies with the same 23-byte message.

Once the connection is established, the remote debugger might want to query the list of tabs using the list_tabs command.

Supported Tools

Currently, all the supported Tools use JSON as the Content format.

DevToolsService

This tool provides a remote debugger with information about the inspectable environment.

Common DevToolsService JSON fields:

• command (required) - the command to perform {string}.
• result (required) - the operation result (in the response message) {integer}.
• data (optional) - auxiliary information associated with the command (both in the request and response messages) {string}.

Available commands:

• ping - keeps the connection alive under certain circumstances, or determines if the application is currently capable of handling request messages.
• version - determines the ChromeDevTools Protocol version supported by the debugged application.
• list_tabs - lists all the debuggable tabs together with their respective URLs opened.

The following result codes are possible:

• OK (0) - the operation completed successfully.
• UNKNOWN_COMMAND (1) - the specified command is not found in the Available commands list.

The request/response examples:

Command
Request content
Response "data" field

ping
{"command":"ping"}
{"command":"ping", "result":0, "data":"ok"}

version
{"command":"version"}
{"command":"version", "result":0, "data":version_id}

list_tabs
{"command":"list_tabs"}
{"command":"list_tabs", "result":0, "data":[[tab1_id,"tab1_url"], [tab2_id,"tab2_url"]]}

V8Debugger

This tool enables communication between a remote debugger and the V8 debuggers running inside a Google Chrome instance.

Common V8Debugger JSON fields:

• command (required) - the command to perform, or an event type {string}.
• result (required in a response) - the operation result {integer}.
• data (required or not, depends on the message type) - auxiliary information associated with the command (both in the request and response messages) {string}.

Available commands:

• attach - requests attachment to a V8 debugger running in the tab specified in the Destination header.
• detach - requests detachment from a V8 debugger running in the tab specified in the Destination header.
• debugger_command - sends a V8 debugger protocol command to a V8 debugger running in the tab specified in the Destination header.
• evaluate_javascript - evaluates JavaScript in the context of a V8 VM associated with the tab specified in the Destination header. No result is returned to the client (use debugger_command "evaluate" instead). When sent after a V8 debugger command while not on a breakpoint, results in the immediate processing of the command (rather than when a breakpoint is hit.)
• navigated - an event that notifies the remote debugger of the fact that the tab URL has changed. The "result" value is always 0 (OK).
• closed - an event that notifies the remote debugger of the fact that the tab has been closed. The "result" value is always 0 (OK).

The following result codes are possible:

• OK (0) - the operation completed successfully (it is a tool-level result code, not a command-level one. For example, the result may be 0 even though the underlying debugger_command request failed. In this case OK means that a valid response has been received from the V8 debugger.)
• ILLEGAL_TAB_STATE (1) - the tab specified in the "Destination" header is in an inappropriate state (i.e. it is attached for an "attach" command or not attached for a "detach" command.)
• UNKNOWN_TAB (2) - the tab specified in the "Destination" header does not exist (it may have been reported in the "list_tabs" response but closed since then.)
• DEBUGGER_ERROR (3) - a generic error occurred while performing the specified operation.
• UNKNOWN_COMMAND (4) - the specified command is not found in the Available commands list.

The request/response examples:

Command
Request Data
Response Data

attach

• Destination: tab_id

• Content: {"command":"attach"}

• Destination: tab_id

• Content: {"command":"attach", "result":result_code}

detach

• Destination: tab_id

• Content: {"command":"detach"}

• Destination: tab_id

• Content: {"command":"detach", "result":result_code}

debugger_command

• Destination: tab_id

• Content: {"command":"debugger_command", "data":debugger_json}

• Destination: tab_id

• Content: {"command":"debugger_command", "result":result_code, "data":debugger_response_json}

evaluate_javascript

• Destination: tab_id
• Content: {"command":"evaluate_javascript", "data":"some_javascript"}
  none

navigated
none (event)

• Destination: tab_id
• Content: {"command":"navigated", "result":0, "data":"new_url"}

closed
none (event)

• Destination: tab_id
• Content: {"command":"closed", "result":0}

Deprecation And Removal

The new debug protocol "WebKit Remote Debug Protocol" is being developed to succeed ChromeDevTools protocol. ChromeDevTools protocol should be considered deprecated. Google Chrome/Chromium browser discontinued its support in 17.0.950.* version (between developer builds 111534 and 111559).

The SDK and EclipseDebugger are going to simultaneously support both protocols behind the single interface starting from 0.3.0 version.

[Anonymous]

Originally posted by: szege...@gmail.com

Looking at the source code of org.chromium.sdk.internal.transport.Message, Content-Length actually expresses the number of characters in the content, not the number of bytes.

I'm actually okay with that as it allows me to read all messages using a single reader and don't have to juggle a Reader and an InputStream?, but you should fix the docs.

[Anonymous]

Originally posted by: szege...@gmail.com

Errata: response for "list_tabs" has wrong "command".

[Anonymous]

Originally posted by: szege...@gmail.com

Your implementation of "backtrace" command uses a boolean argument named "inlineRefs", but it's not documented in the V8 protocol.

[Anonymous]

Originally posted by: szege...@gmail.com

What's the response if the debugged target (i.e. Chromium) doesn't recognize the value of the Tool header?

[Anonymous]

Originally posted by: alexandr...@gmail.com

{"command":"ping", "result":0, "data":"ok"}

[Anonymous]

Originally posted by: rolyv19@gmail.com

I'm sending an "evaluate_javascript" command getting back a "debugger_command" response??!? any thoughts?

[Anonymous]

Originally posted by: szege...@gmail.com

rolyv19: yup, it's compiling that "javascript:void(0);" from "evaluate_javascript" and sending you back an "afterCompile" event about it.

[Anonymous]

Originally posted by: sroussey

Are there any commands for dealing with updates to the DOM?

[Anonymous]

Originally posted by: manisha....@gmail.com

i don't get "navigated" event once the url get changed?? is it working

[Anonymous]

Originally posted by: peter.ry...@gmail.com

sroussey, this should be a feature files in Issues. Could you please file it?

[Anonymous]

Originally posted by: peter.ry...@gmail.com

manisha, yes, this is an important problem. we lost this functionality some time ago. I should be fixed in chrome soon. unfortunately I don't see a proper workaround until then

[Anonymous]

Originally posted by: peter.ry...@gmail.com

manisha, this problem seems to be fixed in chrome now.

[Anonymous]

Originally posted by: shamun.toha@gmail.com

As a developer, can we not remotely controle the browser? From my Java application i would like to connect to Chromium. And i would like to get Chromium renderer or Chromium itself in my Java GUI, and communicate using Object/Class/Method instead of doing it over TCP/UDP??

[Anonymous]

Originally posted by: peter.ry...@gmail.com

Shamun, I'm sorry but this seems to be very far beyond the scope of this project.

[Anonymous]

Originally posted by: splinete...@gmail.com

After successful handshake, which felt great, I send this and it gets ignored by chrome. Could you tell me how exactly should this request look like:

Content-Length:18 Tool:DevToolService?

{command:version}

I tried with and without quotes but nothing works. I encode with UTF8 using C# terminal I wrote. The handshake worked though. I am making my debugger support Chrome: www.remotedebugger.com

[Anonymous]

Originally posted by: splinete...@gmail.com

I found a way: Content-Length:22 Tool:DevToolsService?

{"command": "version"}

Soon google fans will have a new commercial debugger

Daniel www.remotedebugger.com

[Anonymous]

Originally posted by: peter.ry...@gmail.com

Hi Daniel

Good luck with your debugger! Should you have any questions about protocol stuff feel free to contact our http://groups.google.com/group/chromedevtools-dev group.

Also probably I should mention our recent plans on switching to a new protocol (known as WebInspector? protocol). This wiki page will be updated soon once I have a document to refer.

Peter

[Anonymous]

Originally posted by: splinete...@gmail.com

Thanks! Please keep it posted, I'll update my code as you guys update yours, no problem. I am very serious about adding support of google chrome to my debugger. I believe in it. And this wire protocol is very simple way to do it. All I need is 1 complete sample JSON command with header per "supported tool" and a list of commands, and I will just plug it all into an already functioning debugger. It's not that complicated. I think Google will only win if my debugger supports it.

I sent a request to join the group.

I saw a list of command in Remote-debugging section here: http://code.google.com/chrome/devtools/docs/remote-debugging.html May be you are referring to it.

They look interesting. They don't work if I run them under DevToolsService?. How can I run any one of them?

Cheers

Daniel www.remotedebugger.com

[Anonymous]

Originally posted by: peter.ry...@gmail.com

Daniel

If you need you always can spy on the current protocol right from the Eclipse IDE. You just have to enable "Show debugger network communication console" in debug launch configuration.

As to the new protocol -- yes, you found its reference. Unfortunately the announce is not here yet, so you'll have to wait for it to learn the details. New protocol won't work via the old transport protocol (DevToolsService?).

I suggest we move further discussion into chromedevtools-dev group, which is better for this.

Peter

[Anonymous]

Originally posted by: splinete...@gmail.com

Thanks I'll check eclipse and continue this discussion in the group Cheers Dan

[Anonymous]

Originally posted by: elias.po...@gmail.com

Hi, I opended a TCP/IP socket with telnet semantics, handshaked ok, attached ok, and now I am trying to send some more complex commands. I am stuck even though I am using the syntax as eclipse plugin. How do I send a simple version command?

This is what I use:

{"command":"debugger_command","data":{"seq":100,"type":"request","command":"version"}}

Elias

[Anonymous]

Originally posted by: elias.po...@gmail.com

Some more info, the actual socket string I am sending is:

Tool:V8Debugger? Destination:2 Content-Length:86

{"command":"debugger_command","data":{"seq":100,"type":"request","command":"version"}}

[Anonymous]

Originally posted by: peter.ry...@gmail.com

Hi Elias,

let's have this talk in a dedicated place: http://groups.google.com/group/chromedevtools-dev (I'll need to join it first I believe.) This is not a right place for such discussions.

Peter

[Anonymous]

Originally posted by: alexchan...@gmail.com

{"command":"debugger_command","data":{"seq":100,"type":"request","command":"version"}}