This protocol describes service extensions that are made available through
the Dart core libraries, but are not part of the core
Dart VM Service Protocol. Service extension methods are
invoked by prepending the service extension name (e.g.,
"ext.dart.libraryName") to the RPC to be invoked. For example, the
getSocketProfile RPC exposed through dart:io can be executed by invoking
ext.dart.io.getSocketProfile.
This section describes version 4.0 of the dart:io service protocol extensions.
Version getVersion(string isolateId)
The getVersion RPC returns the available version of the dart:io service protocol extensions.
See Version.
SocketProfilingState socketProfilingEnabled(string isolateId, bool enabled [optional])
The socketProfilingEnabled RPC is used to enable/disable the socket profiler
and query its current state. If enabled is provided, the profiler state will
be updated to reflect the value of enabled.
If the state of the socket profiler is changed, a SocketProfilingStateChange
event will be sent on the Extension stream.
See SocketProfilingState.
Success clearSocketProfile(string isolateId)
Removes all statistics associated with prior and current sockets.
See Success.
SocketProfile getSocketProfile(string isolateId)
The getSocketProfile RPC is used to retrieve socket statistics collected by the socket profiler. Only samples collected after socket profiling was enabled by calling socketProfilingEnabled or after the last call to clearSocketProfile will be reported.
OpenFile getOpenFileById(string isolateId, int id);
The getOpenFileById RPC is used to retrieve information about files currently
opened by dart:io from a given isolate.
See getOpenFiles and File.
FileList getOpenFiles(string isolateId);
The getOpenFiles RPC is used to retrieve the list of files currently opened
files by dart:io from a given isolate.
SpawnedProcess getSpawnedProcessById(string isolateId, int id);
The getSpawnedProcessById RPC is used to retrieve information about a process spawned
by dart:io from a given isolate.
See getSpawnedProcesses and SpawnedProcess.
SpawnedProcessList getSpawnedProcesses(string isolateId);
The getSpawnedProcesses RPC is used to retrieve the list of processed opened by
dart:io from a given isolate.
See SpawnedProcessList and SpawnedProcess.
HttpTimelineLoggingState httpEnableTimelineLogging(string isolateId, bool enabled [optional])
The httpEnableTimelineLogging RPC is used to set and inspect the value of
HttpClient.enableTimelineLogging, which determines if HTTP client requests
should be logged to the timeline. If enabled is provided, the state of
HttpClient.enableTimelineLogging will be updated to the value of enabled.
If the value of HttpClient.enableTimelineLogging is changed, a
HttpTimelineLoggingStateChange event will be sent on the Extension stream.
HttpProfile getHttpProfile(string isolateId, int updatedSince [optional])
The getHttpProfile RPC is used to retrieve HTTP profiling information
for requests made via dart:io's HttpClient.
The returned HttpProfile will only include requests issued after
httpTimelineLogging has been enabled or after the last
clearHttpProfile invocation.
If updatedSince is provided, only requests started or updated since the
specified time will be reported. The specified time must be represented in
microseconds since the "Unix epoch".
See HttpProfile.
HttpProfileRequest getHttpProfileRequest(string isolateId, int id)
The getHttpProfileRequest RPC is used to retrieve an instance of HttpProfileRequest,
which includes request and response body data.
See HttpProfileRequest.
Success clearHttpProfile(string isolateId)
The clearHttpProfile RPC is used to clear previously recorded HTTP
requests from the HTTP profiler state. Requests still in-flight after
clearing the profiler state will be ignored by the profiler.
See Success.
class @OpenFile extends Response {
// The unique ID associated with this file.
int id;
// The path of the file.
string name;
}
@OpenFile is a reference to an OpenFile.
class OpenFile extends Response {
// The unique ID associated with this file.
int id;
// The path of the file.
string name;
// The total number of bytes read from this file.
int readBytes;
// The total number of bytes written to this file.
int writeBytes;
// The number of reads made from this file.
int readCount;
// The number of writes made to this file.
int writeCount;
// The time at which this file was last read by this process in milliseconds
// since epoch.
int lastReadTime;
// The time at which this file was last written to by this process in
// milliseconds since epoch.
int lastWriteTime;
}
A OpenFile contains information about reads and writes to a currently opened file.
class OpenFileList extends Response {
// A list of all files opened through dart:io.
@OpenFile[] files;
}
class HttpTimelineLoggingState extends Response {
// Whether Http timeline logging is enabled.
bool enabled;
}
See httpEnableTimelineLogging.
class HttpProfile extends Response {
// The time at which this HTTP profile was built, represented as microseconds
// since the "Unix epoch".
int timestamp;
// The set of recorded HTTP requests.
@HttpProfileRequest[] requests;
}
A collection of HTTP request data collected by the profiler.
See getHttpProfile.
class @HttpProfileRequest extends Response {
// The ID associated with this request.
//
// If the ID does not start with the prefix "from_package/", then there
// will be a corresponding timeline event with the same ID.
string id;
// The ID of the isolate this request was issued from.
string isolateId;
// The HTTP request method associated with this request.
string method;
// The URI to which this HTTP request was sent.
string uri;
// Events related to this HTTP request.
//
// Events which occurred before encountering an error will be reported.
HttpProfileRequestEvent[] events;
// The time at which this request was initiated, represented as microseconds
// since the "Unix epoch".
int startTime;
// The time at which this request was completed, represented as microseconds
// since the "Unix epoch".
int endTime [optional];
// Details about the request.
//
// Will not be provided if the initial request has not yet completed.
HttpProfileRequestData request [optional];
// Details about the response.
//
// Will not be provided if the request has not yet been responded to.
HttpProfileResponseData response [optional];
}
class HttpProfileRequest extends @HttpProfileRequest {
// The body sent as part of this request.
//
// Data written to a request body before encountering an error will be
// reported.
int[] requestBody [optional];
// The body received in response to the request.
int[] responseBody [optional];
}
Profiling information for a single HTTP request.
See HttpProfile.
class HttpProfileRequestData {
// Information about the client connection.
map<string, dynamic> connectionInfo [optional];
// The content length of the request, in bytes.
int contentLength [optional];
// Cookies presented to the server (in the 'cookie' header).
string[] cookies [optional];
// The error associated with the failed request.
string error [optional];
// Whether automatic redirect following was enabled for the request.
bool followRedirects [optional];
// The client request headers.
map<string, dynamic> headers [optional];
// The maximum number of redirects allowed during the request.
int maxRedirects [optional];
// The requested persistent connection state.
bool persistentConnection [optional];
// Proxy authentication details for this request.
HttpProfileProxyData proxyDetails [optional];
}
Information sent as part of the initial HTTP request. If error is present,
the other properties will be null.
See HttpProfileRequest.
class HttpProfileResponseData {
// The series of redirects this connection has been through.
//
// The list will be empty if no redirects were followed. Redirects will be
// updated both in the case of an automatic and a manual redirect.
map<string, dynamic>[] redirects;
// Cookies set by the server (from the 'set-cookie' header).
string[] cookies [optional];
// Information about the client connection.
map<string, dynamic> connectionInfo [optional];
// The client response headers.
map<string, dynamic> headers [optional];
// The compression state of the response.
//
// This specifies whether the response bytes were compressed when they were
// received across the wire and whether callers will receive compressed or
// uncompressed bytes when they listed to this response's byte stream.
string compressionState [optional];
// The reason phrase associated with the status code.
string reasonPhrase [optional];
// Whether the status code is one of the normal redirect codes.
bool isRedirect [optional];
// The persistent connection state returned by the server.
bool persistentConnection [optional];
// The content length of the response body, in bytes.
//
// Returns -1 if the size of the response body is not known in advance.
int contentLength [optional];
// The status code.
int statusCode [optional];
// The time at which the initial response was received, represented as
// microseconds since the "Unix epoch".
int startTime [optional];
// The time at which the response was completed, represented as
// microseconds since the "Unix epoch".
int endTime [optional];
// The error associated with the failed request.
string error [optional];
}
Information received in response to an initial HTTP request.
See HttpProfileRequest.
class HttpProfileProxyData {
string host [optional];
string username [optional];
bool isDirect [optional];
int port [optional];
}
Proxy authentication details associated with an HTTP request.
class HttpProfileRequestEvent {
// The title of the recorded event.
string event;
// The time at which the event occurred, represented as microseconds since
// the "Unix epoch".
int timestamp;
// Any arguments recorded for the event.
map<string, dynamic> arguments [optional];
}
Describes an event related to an HTTP request.
class SocketProfilingState extends Response {
// Whether socket profiling is enabled.
bool enabled;
}
class @SpawnedProcess {
// The unique ID associated with this process.
int id;
// The name of the executable.
string name;
}
@SpawnedProcess is a reference to a SpawnedProcess.
class SpawnedProcess extends Response {
// The unique ID associated with this process.
int id;
// The name of the executable.
string name;
// The process ID associated with the process.
int pid;
// The time the process was started in milliseconds since epoch.
int startedAt;
// The list of arguments provided to the process at launch.
string[] arguments;
// The working directory of the process at launch.
string workingDirectory;
}
A Process contains startup information of a spawned process.
class SpawnedProcessList extends Response {
// A list of processes spawned through dart:io on a given isolate.
@SpawnedProcess[] processes;
}
class Response {
// Every response returned by the VM Service has the
// type property. This allows the client distinguish
// between different kinds of responses.
string type;
}
class SocketProfile extends Response {
// List of socket statistics
SocketStatistic[] sockets;
}
A SocketProfile provides information about statistics of sockets. See getSocketProfile and SocketStatistic.
class SocketStatistic {
// The unique ID associated with this socket.
int id;
// The time, in microseconds, that this socket was created.
int startTime;
// The time, in microseconds, that this socket was closed.
int endTime [optional];
// The time, in microseconds, that this socket was last read from.
int lastReadTime [optional];
// The time, in microseconds, that this socket was last written to.
int lastWriteTime [optional];
// The address of socket.
string address;
// The port of socket.
int port;
// The type of socket. The value is `tcp` or `udp`.
string socketType;
// The number of bytes read from this socket.
int readBytes;
// The number of bytes written to this socket.
int writeBytes;
}
See SocketProfile and getSocketProfile.
class Success extends Response {
}
The Success type is used to indicate that an operation completed successfully.
class Version extends Response {
// The major version number is incremented when the protocol is changed
// in a potentially incompatible way.
int major;
// The minor version number is incremented when the protocol is changed
// in a backwards compatible way.
int minor;
}
| version | comments |
|---|---|
| 1.0 | Initial revision. |
| 1.1 | Added lastReadTime and lastWriteTime properties to SocketStatistic. |
| 1.2 | Added getOpenFiles, getOpenFileById, getSpawnedProcesses, and getSpawnedProcessById RPCs and added OpenFile and SpawnedProcess objects. |
| 1.3 | Added httpEnableTimelineLogging RPC and HttpTimelineLoggingStateChange event, deprecated getHttpEnableTimelineLogging and setHttpEnableTimelineLogging. |
| 1.4 | Updated httpEnableTimelineLogging parameter enable to enabled. enable will continue to be accepted. |
| 1.5 | Added socketProfilingEnabled RPC and SocketProfilingStateChanged event, deprecated startSocketProfiling and pauseSocketProfiling. |
| 1.6 | Added isSocketProfilingAvailable, isHttpTimelineLoggingAvailable, isHttpProfilingAvailable, removed deprecated RPCs startSocketProfiling, |
pauseSocketProfiling, getHttpEnableTimelineLogging, and setHttpEnableTimelineLogging. |
|
| 2.0 | Changed the type of the id property of @HttpProfileRequestRef and |
HttpProfileRequestRef from int to String. Changed the type of |
|
SocketStatistic.id from int to String. Changed the type of the id |
|
parameter of getHttpProfileRequest from int to String. Changed the name of |
|
the enable parameter of httpEnableTimelineLogging to enabled. |
|
| 3.0 | Added isSocketProfilingAvailable, isHttpTimelineLoggingAvailable, |
and isHttpProfilingAvailable methods. Removed deprecated |
|
startSocketProfiling, pauseSocketProfiling, getHttpEnableTimelineLogging, |
|
and setHttpEnableTimelineLogging methods. |
|
| 4.0 | Made the updatedSince parameter of getHttpProfile require the time to |
| be represented in microseconds since the "Unix epoch" instead of as a timestamp | |
on the monotonic clock used by the timeline. Made the timestamp property of |
|
HttpProfile represent time in microseconds since the "Unix epoch" instead of |
|
as a timestamp on the monotonic clock used by the timeline. Added events |
|
property to @HttpProfileRequest and HttpProfileRequest. Made the startTime |
|
and endTime properties of @HttpProfileRequest and HttpProfileRequest |
|
| represent time in microseconds since the "Unix epoch" instead of as timestamps | |
on the monotonic clock used by the timeline. Removed the events and method |
|
properties from HttpProfileRequestData. Made the cookies property of |
|
HttpProfileRequestData optional. Made the startTime and endTime properties |
|
of HttpProfileResponseData represent time in microseconds since the "Unix |
|
| epoch" instead of as timestamps on the monotonic clock used by the timeline. | |
Made the cookies, headers, compressionState, reasonPhrase, isRedirect, |
|
persistentConnection, contentLength, statusCode, and startTime |
|
properties of HttpProfileResponseData optional. Made the isDirect property |
|
of HttpProfileProxyData optional. Made the timestamp property of |
|
HttpProfileRequestEvent represent time in microseconds since the "Unix epoch" |
|
| instead of as a timestamp on the monotonic clock used by the timeline. |