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
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: ... ... }
The types returned by the VM Service fit into a type hierarchy, with a subtyping relationship as indicated by the following indented list:
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.
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.
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.
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 property. This provides the VM-internal type name of an object, and is provided only when this type name differs from the type property.
TODO
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 |
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 |
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 |
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 |
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 |
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 |
TODO: Add type and id?
Object properties:
keys | values | comments |
---|---|---|
script | @Script | |
tokenPos | int | |
function | @Function | |
code | @Code | |
vars | List of FrameVar |
Object properties:
keys | values | comments |
---|---|---|
name | String | |
value | @Instance |
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 |
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 |
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 |
Object properties:
keys | values | comments |
---|---|---|
type | “Location” | |
script | @Script | |
tokenPos | int |
Reference properties:
keys | values | comments |
---|---|---|
type | “@null”, “null” | |
id | String | |
valueAsString | String |
Object properties:
TODO.
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
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 |
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 |
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” |
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 |