Derek Xu
32dffaa8d8
- Deprecate `getAvailableCachedCpuSamples` and `getCachedCpuSamples` RPCs. - Deprecate the `cachedUserTags` parameter of `DartDevelopmentService.startDartDevelopmentService`. - Deprecate the `DartDevelopmentService.cachedUserTags` getter. Issue: https://github.com/dart-lang/sdk/issues/61267 Change-Id: I9f9088a810584c2031d8475c767a312dff6ab2cd Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/444100 Reviewed-by: Ben Konyi <bkonyi@google.com> Commit-Queue: Derek Xu <derekx@google.com>
377 lines
13 KiB
Markdown
377 lines
13 KiB
Markdown
# Dart Development Service Protocol 2.1
|
|
|
|
This document describes _version 2.1_ of the Dart Development Service Protocol.
|
|
This protocol is an extension of the Dart VM Service Protocol and implements it
|
|
in it's entirety. For details on the VM Service Protocol, see the [Dart VM Service Protocol Specification][service-protocol].
|
|
|
|
The Service Protocol uses [JSON-RPC 2.0][].
|
|
|
|
[JSON-RPC 2.0]: http://www.jsonrpc.org/specification
|
|
|
|
## Table of Contents
|
|
|
|
- [RPCs, Requests, and Responses](#rpcs-requests-and-responses)
|
|
- [Events](#events)
|
|
- [Types](#types)
|
|
- [IDs and Names](#ids-and-names)
|
|
- [Revision History](#revision-history)
|
|
- [Public RPCs](#public-rpcs)
|
|
- [getAvailableCachedCpuSamples](#getavailablecachedcpusamples)
|
|
- [getCachedCpuSamples](#getcachedcpusamples)
|
|
- [getClientName](#getclientname)
|
|
- [getDartDevelopmentServiceVersion](#getdartdevelopmentserviceversion)
|
|
- [getLogHistorySize](#getloghistorysize)
|
|
- [getPerfettoVMTimeline](#getperfettovmtimeline)
|
|
- [getStreamHistory](#getstreamhistory)
|
|
- [postEvent](#postevent)
|
|
- [requirePermissionToResume](#requirepermissiontoresume)
|
|
- [setClientName](#setclientname)
|
|
- [setLogHistorySize](#setloghistorysize)
|
|
- [Public Types](#public-types)
|
|
- [AvailableCachedCpuSamples](#availablecachedcpusamples)
|
|
- [CachedCpuSamples](#cachedcpusamples)
|
|
- [ClientName](#clientname)
|
|
- [DartDevelopmentServiceVersion](#dartdevelopmentserviceversion)
|
|
- [Size](#size)
|
|
- [StreamHistory](#streamhistory)
|
|
|
|
## RPCs, Requests, and Responses
|
|
|
|
See the corresponding section in the VM Service protocol [here][service-protocol-rpcs-requests-and-responses].
|
|
|
|
## Events
|
|
|
|
See the corresponding section in the VM Service protocol [here][service-protocol-events].
|
|
|
|
## Binary Events
|
|
|
|
See the corresponding section in the VM Service protocol [here][service-protocol-binary-events].
|
|
|
|
## Types
|
|
|
|
See the corresponding section in the VM Service protocol [here][service-protocol-types].
|
|
|
|
## IDs and Names
|
|
|
|
See the corresponding section in the VM Service protocol [here][service-protocol-ids-and-names].
|
|
|
|
## Streams
|
|
|
|
For a list of core VM service streams, see [streamListen][service-protocol-streams].
|
|
|
|
DDS will keep a history of events on certain streams and send historical events
|
|
when a client first subscribes to a stream with history. These streams currently
|
|
consist of the following:
|
|
|
|
- `Logging`
|
|
- `Stdout`
|
|
- `Stderr`
|
|
- `Extension`
|
|
|
|
In addition, subscribing to the `Service` stream will result in a `ServiceRegistered`
|
|
event being sent to the subscribing client for each existing service extension.
|
|
|
|
From protocol version 1.4, custom streams of any name can be listened to via DDS.
|
|
|
|
## Public RPCs
|
|
|
|
The DDS Protocol supports all [public RPCs defined in the VM Service protocol][service-protocol-public-rpcs].
|
|
|
|
### getAvailableCachedCpuSamples
|
|
|
|
```
|
|
AvailableCachedCpuSamples getAvailableCachedCpuSamples();
|
|
```
|
|
|
|
The _getAvailableCachedCpuSamples_ RPC is deprecated and will always return an
|
|
_AvailableCachedCpuSamples_ object containing a single property named
|
|
_cacheNames_ with an empty array as its value.
|
|
|
|
See [AvailableCachedCpuSamples](#availablecachedcpusamples).
|
|
|
|
### getCachedCpuSamples
|
|
|
|
```
|
|
CachedCpuSamples getCachedCpuSamples(string isolateId, string userTag);
|
|
```
|
|
|
|
The _getCachedCpuSamples_ RPC is deprecated and will always return a
|
|
_CachedCpuSamples_ object containing properties with meaningless placeholder
|
|
values.
|
|
|
|
See [CachedCpuSamples](#cachedcpusamples).
|
|
|
|
### getClientName
|
|
|
|
```
|
|
ClientName getClientName()
|
|
```
|
|
|
|
The _getClientName_ RPC is used to retrieve the name associated with the currently
|
|
connected VM service client. If no name was previously set through the
|
|
[setClientName](#setclientname) RPC, a default name will be returned.
|
|
|
|
See [ClientName](#clientname)
|
|
|
|
### getDartDevelopmentServiceVersion
|
|
|
|
```
|
|
Version getDartDevelopmentServiceVersion()
|
|
```
|
|
|
|
The _getDartDevelopmentServiceVersion_ RPC is used to determine what version of
|
|
the Dart Development Service Protocol is served by a DDS instance.
|
|
|
|
See [Version](#version).
|
|
|
|
|
|
### getLogHistorySize
|
|
|
|
```
|
|
Size getLogHistorySize()
|
|
```
|
|
|
|
The _getLogHistorySize_ RPC is used to retrieve the current size of the log
|
|
history buffer. If the returned [Size](#size) is zero, then log history is
|
|
disabled.
|
|
|
|
See [Size](#size).
|
|
|
|
### getPerfettoVMTimelineWithCpuSamples
|
|
|
|
```
|
|
PerfettoTimeline getPerfettoVMTimelineWithCpuSamples(int timeOriginMicros [optional],
|
|
int timeExtentMicros [optional])
|
|
```
|
|
|
|
The _getPerfettoVMTimelineWithCpuSamples_ RPC functions nearly identically to
|
|
the VM Service Protocol's _getPerfettoVMTimeline_ RPC, except the `trace` field
|
|
of the `PerfettoTimeline` response returned by this RPC will be a Base64 string
|
|
encoding a Perfetto-format trace that includes not only all timeline events
|
|
in the specified time range, but also all CPU samples from all isolates in the
|
|
specified time range.
|
|
|
|
See the documentation of _getPerfettoVMTimeline_ and _getPerfettoCpuSamples_ in
|
|
the [Dart VM Service Protocol Specification][service-protocol].
|
|
|
|
### getStreamHistory
|
|
|
|
```
|
|
StreamHistory getStreamHistory(string streamId)
|
|
```
|
|
|
|
The _getStreamHistory_ RPC is used to retrieve historical events for streams
|
|
which support event history (see [Streams](#streams) for a list of supported
|
|
streams).
|
|
|
|
See [StreamHistory](#streamhistory).
|
|
|
|
### postEvent
|
|
|
|
```
|
|
void postEvent(String stream, String eventKind, Map eventData)
|
|
```
|
|
The _postEvent_ RPC is used to send events to custom Event streams.
|
|
|
|
### readyToResume
|
|
|
|
```
|
|
Success readyToResume(string isolateId)
|
|
```
|
|
|
|
The _readyToResume_ RPC indicates to DDS that the current client is ready
|
|
to resume the isolate.
|
|
|
|
If the current client requires that approval be given before resuming an
|
|
isolate, this method will:
|
|
|
|
- Update the approval state for the isolate.
|
|
- Resume the isolate if approval has been given by all clients which
|
|
require approval.
|
|
|
|
Returns a collected sentinel if the isolate no longer exists.
|
|
|
|
See [Success](#success).
|
|
|
|
### requirePermissionToResume
|
|
|
|
```
|
|
Success requirePermissionToResume(bool onPauseStart [optional],
|
|
bool onPauseReload[optional],
|
|
bool onPauseExit [optional])
|
|
```
|
|
|
|
The _requirePermissionToResume_ RPC is used to change the pause/resume behavior
|
|
of isolates by providing a way for the VM service to wait for approval to resume
|
|
from some set of clients. This is useful for clients which want to perform some
|
|
operation on an isolate after a pause without it being resumed by another client.
|
|
These clients should invoke [readyToResume](#readyToResume) instead of [resume](resume)
|
|
to indicate to DDS that they have finished their work and the isolate can be resumed.
|
|
|
|
If the _onPauseStart_ parameter is `true`, isolates will not resume after pausing
|
|
on start until the client sends a `resume` request and all other clients which
|
|
need to provide resume approval for this pause type have done so.
|
|
|
|
If the _onPauseReload_ parameter is `true`, isolates will not resume after pausing
|
|
after a reload until the client sends a `resume` request and all other clients
|
|
which need to provide resume approval for this pause type have done so.
|
|
|
|
If the _onPauseExit_ parameter is `true`, isolates will not resume after pausing
|
|
on exit until the client sends a `resume` request and all other clients which
|
|
need to provide resume approval for this pause type have done so.
|
|
|
|
**Important Notes:**
|
|
|
|
- All clients with the same client name share resume permissions. Only a
|
|
single client of a given name is required to provide resume approval.
|
|
- When a client requiring approval disconnects from the service, a paused
|
|
isolate may resume if all other clients requiring resume approval have
|
|
already given approval. In the case that no other client requires resume
|
|
approval for the current pause event, the isolate will be resumed if at
|
|
least one other client has attempted to [resume](resume) the isolate.
|
|
- Resume permission behavior can be bypassed using the [VmService.resume]
|
|
RPC, which is treated as a user-initiated resume that force resumes
|
|
the isolate. Tooling relying on resume permissions should use
|
|
[readyToResume](#readyToResume) instead of [resume](resume) to avoid force
|
|
resuming the isolate.
|
|
|
|
See [Success](#success).
|
|
|
|
### requireUserPermissionToResume
|
|
|
|
```
|
|
Success requireUserPermissionToResume(bool onPauseStart [optional],
|
|
bool onPauseExit [optional])
|
|
```
|
|
|
|
The _requireUserPermissionToResume_ RPC notifies DDS if it should wait
|
|
for a [resume](resume) request to resume isolates paused on start or
|
|
exit.
|
|
|
|
This RPC should only be invoked by tooling which launched the target Dart
|
|
process and knows if the user indicated they wanted isolates paused on
|
|
start or exit.
|
|
|
|
See [Success](#success).
|
|
|
|
### setClientName
|
|
|
|
```
|
|
Success setClientName(string name)
|
|
```
|
|
|
|
The _setClientName_ RPC is used to set a name to be associated with the currently
|
|
connected VM service client. If the _name_ parameter is a non-empty string, _name_
|
|
will become the new name associated with the client. If _name_ is an empty string,
|
|
the client's name will be reset to its default name.
|
|
|
|
See [Success](#success).
|
|
|
|
### setLogHistorySize
|
|
|
|
```
|
|
Success setLogHistorySize(int size)
|
|
```
|
|
|
|
The _setLogHistorySize_ RPC is used to set the size of the ring buffer used for
|
|
caching a limited set of historical log messages. If _size_ is 0, logging history
|
|
will be disabled. The maximum history size is 100,000 messages, with the default
|
|
set to 10,000 messages.
|
|
|
|
See [Success](#success).
|
|
|
|
## Public Types
|
|
|
|
The DDS Protocol supports all [public types defined in the VM Service protocol][service-protocol-public-types].
|
|
|
|
### AvailableCachedCpuSamples
|
|
|
|
```
|
|
class AvailableCachedCpuSamples extends Response {
|
|
// A list of UserTag names associated with CPU sample caches.
|
|
string[] cacheNames;
|
|
}
|
|
```
|
|
|
|
A collection of [UserTag] names associated with caches of CPU samples.
|
|
|
|
See [getAvailableCachedCpuSamples](#getavailablecachedcpusamples).
|
|
|
|
### CachedCpuSamples
|
|
|
|
```
|
|
class CachedCpuSamples extends CpuSamples {
|
|
// The name of the UserTag associated with this cache of samples.
|
|
string userTag;
|
|
|
|
// Provided if the CPU sample cache has filled and older samples have been
|
|
// dropped.
|
|
bool truncated [optional];
|
|
}
|
|
```
|
|
|
|
An extension of [CpuSamples](#cpu-samples) which represents a set of cached
|
|
samples, associated with a particular [UserTag] name.
|
|
|
|
See [getCachedCpuSamples](#getcachedcpusamples).
|
|
|
|
### ClientName
|
|
|
|
```
|
|
class ClientName extends Response {
|
|
// The name of the currently connected VM service client.
|
|
string name;
|
|
}
|
|
```
|
|
|
|
See [getClientName](#getclientname) and [setClientName](#setclientname).
|
|
|
|
### Size
|
|
|
|
```
|
|
class Size extends Response {
|
|
int size;
|
|
}
|
|
```
|
|
|
|
A simple object representing a size response.
|
|
|
|
### StreamHistory
|
|
|
|
```
|
|
class StreamHistory extends Response {
|
|
// A list of historical Events for a stream.
|
|
List<Event> history;
|
|
}
|
|
```
|
|
|
|
See [getStreamHistory](#getStreamHistory).
|
|
|
|
## Revision History
|
|
|
|
version | comments
|
|
------- | --------
|
|
1.0 | Initial revision
|
|
1.1 | Added `getDartDevelopmentServiceVersion` RPC.
|
|
1.2 | Added `getStreamHistory` RPC.
|
|
1.3 | Added `getAvailableCachedCpuSamples` and `getCachedCpuSamples` RPCs.
|
|
1.4 | Added the ability to subscribe to custom streams (which can be specified when calling `dart:developer`'s `postEvent`).
|
|
1.5 | Added `getPerfettoCpuSamples` RPC.
|
|
1.6 | Added `postEvent` RPC.
|
|
2.1 | Deprecated `getAvailableCachedCpuSamples` and `getCachedCpuSamples` RPCs.
|
|
|
|
[resume]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#resume
|
|
[success]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#success
|
|
[version]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#version
|
|
[cpu-samples]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#cpusamples
|
|
|
|
[service-protocol]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md
|
|
[service-protocol-rpcs-requests-and-responses]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#rpcs-requests-and-responses
|
|
[service-protocol-events]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#events
|
|
[service-protocol-streams]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#streamlisten
|
|
[service-protocol-binary-events]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#binary-events
|
|
[service-protocol-types]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#types
|
|
[service-protocol-ids-and-names]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#ids-and-names
|
|
[service-protocol-public-rpcs]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#public-rpcs
|
|
[service-protocol-public-types]: https://github.com/dart-lang/sdk/blob/main/runtime/vm/service/service.md#public-types
|