Dart VM Service Protocol

NOTE: The service api is still changing rapidly. If you use the service api, expect to encounter non-compatible changes.

Description How to start JSON Websocket

Types

Every response returned by the VM Service has the type property. This allows the client distinguish between different kinds of responses. For example, global information about the VM is encoded in an response of type VM and information about an isolate is encoded in an response of type Isolate.

If the type name of a response begins with an @ character then that response is a reference. If the type name of a response does not begin with an @ character then that response is an object (or sometimes full object). A reference is meant to be a subset of a full object with just enough information for the client to generate a reasonable-looking link.

For example, an isolate reference may look like this...

{
  type: "@Isolate",
  id: "isolates/123",
  name: "worker"
}

... and a full isolate object would have additional properties:

{
  type: "Isolate",
  id: "isolates/123",
  name: "worker"
  entry: ...
  heaps: ...
  topFrame: ...
  ...
}

IDs

Most responses returned by the VM Service have an id property. An id is used to request an object from the VM. Each id is unique; that is to say, If two responses have the same id, they refer to the same object. The converse is not true: the same object may occasionally be returned with two different ids.

An id is either global or relative. Global ids can be requested from the VM directly by requesting the uri /{global id}.

The following is a list of known, fixed global ids:

id	uri	type
vm	/vm	VM
flags	/flags	FlagList

In addition, all isolates have global ids, but these ids are dynamically generated. An isolate with an id like isolates/123 would be available at the uri /isolates/123.

Relative ids are used to refer to objects that are owned by an isolate. Relative ids can be requested from the VM directly by requesting the uri /{isolate id}/{relative id}.

For example, we can get information about a class with id classes/Foo from isolate isolates/123 by requesting the uri /isolates/123/classes/Foo from the VM.

The client must not parse ids -- they must be treated as opaque strings. We reserve the right to change the ids of objects.

Names

Many responses have the name property. Names are provided so that objects can be displayed in a way that a Dart language programmer would find sensible.

Note that names are not in any way unique. Many objects will have the same name.

Occasionally responses will have the vmName property. This represents the internal names used to refer to an object inside the VM itself. The vmName of an object is only provided when it differs from the name property; when vmName is not present, the client may assume the name and vmName are the same.

Events

TODO

Catalog of Types

@AbstractType

AbstractType

Breakpoint

TODO: Get rid of Location or else use it more generally.

keys	values	comments
type	“Breakpoint”
id	String
breakpointNumber	int
enabled	bool
resolved	bool
location	Location

@Class

keys	values	comments
type	“@Class”
id	String
name	String
vmName?	String

Class

keys	values	comments
type	“@Class”
id	String
name	String
vmName?	String
error?	Error	Error encountered during class finalization
implemented	bool
abstract	bool
patch	bool
finalized	bool
const	bool
super?	@Class	Super class
library	@Library	Owning library
script?	@Script	Script containing class source
tokenPos?	int	starting token position of class source in script
endTokenPos?	int	end token position of class source in script
interfaces	List of @Class	interfaces this class has implemented
fields	List of @Field
functions	List of @Function
subclasses	List of @Class	classes which extend this class.
canonicalTypes	[@TypeList]	kill?
allocationStats	ClassHeapStats

ClassHeapStats

keys	values	comments
type	“ClassHeapStats”
id	String
class	@Class
new	List of int	Allocation statistics for new space. See note below on allocation statistics list format.
old	List of int	Allocation statistics for old space. See note below on allocation statistics list format.
promotedInstances	int	number of instances promoted at last new-space GC.
promotedBytes	int	number of bytes promoted at last new-space GC.

Allocation statistics list format | index | value | description | --- | --- | --- | | 0 | int | Instances allocated before last GC | | 1 | int | Bytes allocated before last GC | | 2 | int | Instances alive after last GC | | 3 | int | Bytes alive after last GC | | 4 | int | Instances allocated since last GC | | 5 | int | Bytes allocated since last GC | | 6 | int | Instances allocated since last accumulator reset | | 7 | int | Bytes allocated since last accumulator reset |

@Code

keys	values	comments
type	“@Code”
id	String
name	String
vmName?	String
start	String	starting address of code
end	String	ending address of code
isOptimized	bool
isAlive	bool
kind	String
function	@Function

Code

keys	values	comments
type	“@Code”
id	String
name	String
vmName?	String
start	String	starting address of code
end	String	ending address of code
isOptimized	bool
isAlive	bool
kind	String
function	@Function
object_pool	List of @Object
disassembly	List of String	See note below on disassembly list format

Disassembly list format | index | value | description | --- | --- | --- | | 0 | String | Address of instruction | 1 | String | Hex encoding of instruction | 2 | String | Human encoding of instruction | 0 + (3 * K) | String | Address of Kth instruction | 1 + (3 * K) | String | Hex encoding of instruction of Kth instruction | 2 + (3 * K) | String | Human encoding of instruction of Kth instruction

DebuggerEvent

keys	values	comments
type	“DebuggerEvent”
id	String	TODO: Remove
eventType	String	“BreakpointReached”, “BreakpointResolved”, “ExceptionThrown”, “IsolateCreated”, “IsolateShutdown”, or “IsolateInterrupted”
isolate	@Isolate
breakpoint?	Breakpoint	for eventTypes “BreakpointResolved” and "BreakpointReached TODO: Maybe make this @Breakpoint?
exception?	@Instance	for eventType “ExceptionThrown”

Error

TODO: Drop id from Error.

keys	values	comments
type	“Error”
id	String	always empty
kind	String
message	String

@Field

keys	values	comments
type	“@Field”
id	String
name	String
vmName?	String
value?	Instance	value associated with static field <-- do we want to include this in a field reference?
owner	@Library,@Class	Owning library or class <-- handling of owner is inconsistent with Function
declared_type	@AbstractType
static	bool
final	bool
const	bool

Field

keys	values	comments
type	“Field”
id	String
name	String
vmName?	String
value?	Instance	value associated with static field
owner	@Library	Owning library <-- handling of owner is inconsistent with Function
owner	@Class	Owning class <-- handling of owner is inconsistent with Function
declared_type	@AbstractType
static	bool
final	bool
const	bool
guard_nullable	bool	can this field hold a null?
guard_class	String OR @Class	“unknown”, “dynamic”, or a class
guard_length	String OR int	“unknown”, “variable”, or length of array
script?	@Script	Script containing field source
tokenPos?	int	starting token position of field source in script

Frame

TODO: Add type and id?

keys	values	comments
script	@Script
tokenPos	int
function	@Function
code	@Code
vars	List of FrameVar

FrameVar

keys	values	comments
name	String
value	@Instance

@Function

keys	values	comments
type	“@Function”
id	String
name	String
vmName?	String
owningLibrary?	@Library	Set for non-top level functions
owningClass?	@Class	Set for non-top level functions
parent?	@Function	Parent function
kind	String

Function

keys	values	comments
type	“@Function”
id	String
name	String
vmName?	String
owningLibrary	@Library	Set for non-top level functions
owningClass	@Class	Set for non-top level functions
parent?	@Function	Parent function
kind	String
static	bool
const	bool
optimizable	bool
inlinable	bool
usage_counter	int
optimized_call_site_count	int
deoptimizations	int
script?	@Script	Script containing function source
tokenPos?	int	starting token position of function source in script
endTokenPos?	int	end token position of function source in script
unoptimized_code	@Code
code	@Code	Current code

@Isolate

keys	values	comments
type	“@Isolate”
id	String
mainPort	String	kill?
name	String

Isolate

keys	values	comments
type	“Isolate”
id	String
mainPort	String	kill?
name	String
entry?	@Function
heaps	???
topFrame?	Frame
livePorts	int
pauseOnExit	bool
pauseEvent?	DebuggerEvent
rootLib	@Library
timers	???
tagCounters	???
error?	Error
canonicalTypeArguments		kill?
libs	List of @Library
features	List of String

@Library

keys	values	comments
type	“@Library”
id	String
name	String
vmName?	String	Internal vm name. Provided only when different from ‘name’.
url	String

Library

keys	values	comments
type	“Library”
id	String
name	String
vmName?	String	Internal vm name. Provided only when different from ‘name’.
classes	List of @Class
imports	List of @Library
variables	List of ...
functions	List of @Function
scripts	List of @Script

Location

keys	values	comments
type	“Location”
script	@Script
tokenPos	int

@Null

TODO: Split Null from the other Sentinel types.

keys	values	comments
type	“@Null”
id	String
valueAsString	String

PcDescriptor

@Script

| keys | values | comments | example | | --- | --- | --- | type | “@Script” | | id | String | name | String | vmName? | String | Internal vm name. Provided only when different from ‘name’. | kind | String

Script

keys	values	comments
type	“@Script”
id	String
name	String
vmName?	String	Internal vm name. Provided only when different from ‘name’.
kind	String
owningLibrary	@Library
source	String
tokenPosTable	List of list of int. See note below about token line format.

Token line format | index | value | comments | --- | --- | --- | 0 | int | line number | 1 | int | first token position | 2 | int | first column number | ... | ... | ... | 1 + (2 * k) | int | kth token position | 2 + (2 * k) | int | kth column number

VM

keys	values	comments
type	“VM”
id	String
targetCPU	String
hostCPU	String
date	String	kill?
version	String
pid	int
assertsEnabled	bool	TODO: move to features?
typeChecksEnabled	bool	TODO: move to features?
uptime	double	seconds since vm started
“isolates”	List of @Isolate