sdk/runtime/vm/service/protocol.md

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: ...
  ...
}

Type Hierarchy

The types returned by the VM Service fit into a type hierarchy, with a subtyping relationship as indicated by the following indented list:

Object
    ClassHeapStats
    Class
    Code
    Context
    Counter
    Error
    Field
    FrameVar
    Frame
    Function
    Gauge
    Instance
        AbstractType
	    BoundedType
	    TypeParameter
	    TypeRef
	    Type
        List
        Sentinel  // TODO - subtype of Instance or not?
        String
        bool
        double
        int
        null
    Isolate
    Library
    Location
    Script
    ServiceError
    ServiceEvent
    Socket
    TypeArguments  // TODO - expose?
    VM

TODO: How to put links in a pre in markdown?

A subtype is guaranteed to provide all of the properties of its parent type. For example, an int can be used as an Instance.

The subtyping relationship also holds for reference types. For example, @int can be used as an @Instance.

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.

Private Properties

Some properties returned by the VM Service begin with an underscore (_) character. These properties are called private properties. Private properties provide private information about the VM's implementation. Private properties may be added, removed, or changed at any time with any release of the VM. They are provided for those tools that need this level of internal access, such as the Observatory.

For example, some responses will have the _vmType nnnproperty. This provides the VM-internal type name of an object, and is provided only when this type name differs from the type property.

Events

TODO

Catalog of Types

AbstractType

Breakpoint

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

Object properties:

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

Class

Reference properties:

keys	values	comments
type	"@Class", "Class"
id	String
name	String
_vmName?	String

Object properties:

keys	values	comments
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

Object properties:

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

Reference properties:

keys	values	comments
type	"@Code", "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 properties:

keys	values	comments
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

Error

TODO: Drop id from Error.

Object properties:

keys	values	comments
type	"Error"
_vmType?	String	VM internal name for this type. Provided only when different from 'type'
id	String	always empty
kind	String
message	String

Field

Reference properties:

keys	values	comments
type	"@Field", "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

Object properties:

keys	values	comments
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?

Object properties:

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

FrameVar

Object properties:

keys	values	comments
name	String
value	@Instance

Function

Reference properties:

keys	values	comments
type	"@Function", "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

Object properties:

keys	values	comments
static	bool	TODO: not consistent with Field
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

Reference properties:

keys	values	comments
type	"@Isolate", "Isolate"
id	String
mainPort	String	kill?
name	String

Object properties:

keys	values	comments
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

Reference properties:

keys	values	comments
type	"@Library", "Library"
id	String
name	String
_vmName?	String	VM-internal name. Provided only when different from 'name'.
url	String

Object properties:

keys	values	comments
classes	List of @Class
imports	List of @Library
variables	List of ...
functions	List of @Function
scripts	List of @Script

Location

Object properties:

keys	values	comments
type	"Location"
script	@Script
tokenPos	int

null

Reference properties:

keys	values	comments
type	"@null", "null"
id	String
valueAsString	String

Object properties:

TODO.

Object

Object is the supertype of all responses returned by the VM Service. It does not necessarily refer to an Object at the Dart language level (see Instance).

Reference properties:

keys	values	comments
type	"@Object", "Object" or subtype
_vmType?	String	VM internal name for this type. Provided only when different from 'type'
id	String

Object properties: none

PcDescriptor

Script

Reference properties:

| keys | values | comments | example | | --- | --- | --- | type | "@Script", "Script" | | id | String | name | String | _vmName? | String | VM-internal name. Provided only when different from 'name'. | kind | String

Object properties:

keys	values	comments
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

Sentinel

TODO: Enumerate known Sentinels
TODO: Should this even have an id? Maybe a kind instead.

Object properties:

keys	values	comments
type	"Sentinel"
id	String
valueAsString	String

ServiceEvent

Object properties:

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

VM

Object properties:

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