transport/proto/transport.proto

/*
 * Copyright (C) 2016 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
syntax = "proto3";

package profiler.proto;
option java_package = "com.android.tools.profiler.proto";
option java_outer_classname = "Transport";

import "commands.proto";
import "common.proto";

service TransportService {
  // Gets current timestamp that used in the device's data.
  // A client may use this API to relate data' timestamps to other
  // clocks such as the desktop's calendar time.
  rpc GetCurrentTime(TimeRequest) returns (TimeResponse) {}

  // Gets version.
  rpc GetVersion(VersionRequest) returns (VersionResponse) {}

  // Query for cached byte data associated with some ID. Other services may
  // return an ID which can be used to fetch data using this central cache.
  rpc GetBytes(BytesRequest) returns (BytesResponse) {}

  // Studio-side only: gets the currently connected devices.
  // TODO: replace with command in the new pipeline.
  // TODO: expand with timing information for historical requests.
  rpc GetDevices(GetDevicesRequest) returns (GetDevicesResponse) {}

  // Studio-side only: get the running processes of a given device
  // TODO: replace with command in the new pipeline.
  rpc GetProcesses(GetProcessesRequest) returns (GetProcessesResponse) {}

  // Query for whether the agent is alive.
  // TODO: replace with command in the new pipeline.
  rpc GetAgentStatus(AgentStatusRequest) returns (AgentData) {}

  // Executes a |Command| on the daemon.
  rpc Execute(ExecuteRequest) returns (ExecuteResponse) {}

  // Streams events as they are being generated by the app or the perfd daemon.
  // This API is most useful for getting all profiling data regardless of any
  // filtering, for example, from a device.
  rpc GetEvents(GetEventsRequest) returns (stream Event) {}

  // Gets all the event groups (events that share the same group_id) that
  // intersect the range [|from_timestamp|, |to_timestamp|]. If the paramter
  // |end| is used, an event_group will be considered "open" until such an event
  // shows up. For example if we have a "SESSION_STARTED" at time 1,  and the
  // range requested is [2,3], and the |end| field is set to SESSEND_SESSION",
  // then the event group will be considered opened, and this intersecting the
  // range.
  rpc GetEventGroups(GetEventGroupsRequest) returns (GetEventGroupsResponse) {}

  // Studio-side only - delete events in the database that match the request's
  // parameters.
  rpc DeleteEvents(DeleteEventsRequest) returns (DeleteEventsResponse) {}
}

message TimeRequest {
  int64 stream_id = 1;
}

message TimeResponse {
  // What's used as timestamps in all profiler data (unless otherwise
  // specified). (a.k.a: Timestamp from clock_gettime(CLOCK_MONOTONIC, ...), ns
  // precision.)
  int64 timestamp_ns = 1;

  // The number of microseconds since the Epoch.
  // (a.k.a: Timestamp from gettimeofday, us precision.)
  int64 epoch_timestamp_us = 2;
}

message VersionRequest {
  int64 stream_id = 1;
}

message VersionResponse {
  string version = 1;
}

message BytesRequest {
  int64 stream_id = 1;
  // ID for fetching contents from a cache. The value will always be safe to use
  // as a filename, if you want to cache the contents locally to disk for
  // example.
  string id = 2;
}

message BytesResponse {
  // Byte contents from a cache, or "" if no data was found associated with the
  // cache key used to fetch it, or if the data was removed after some timeout.
  bytes contents = 1;
}

message GetDevicesRequest {}

message GetDevicesResponse {
  repeated Device device = 1;
}

message GetProcessesRequest {
  int64 device_id = 1;
}

message GetProcessesResponse {
  repeated Process process = 2;
}

message AgentStatusRequest {
  int64 device_id = 1;
  int32 pid = 2;
}

message ExecuteRequest {
  Command command = 1;
}

message ExecuteResponse {
  // Command id as generated by the pipeline when Execute(...) is called.
  int32 command_id = 1;
}

message GetEventsRequest {}

// Every field in this message serves the purpose of filtering if it is set.
// When multiple fields are set, all filtering conditions must be met so an
// event group can be returned.
//
// The default value of a proto type (e.g., 0 for int64) is not considered
// valid. For instance, 0 is not a valid session ID.
message GetEventGroupsRequest {
  // An event is returned if |stream_id| matches.
  int64 stream_id = 1;
  // An event is returned if |pid| matches.
  int32 pid = 2;
  // An event is returned if |kind| matches.
  Event.Kind kind = 3;
  // An event is returned if |group_id| matches.
  int64 group_id = 4;
  // An event is returned if |command_id| matches.
  int32 command_id = 5;
  // When |from_timestamp| and/or |to_timestamp| are set, an event group is
  // returned including the events during with the range, also including the
  // last event before |from_timestamp| and the first one after |to_timestamp|
  // in each group.
  int64 from_timestamp = 6;  // inclusive
  int64 to_timestamp = 7;    // inclusive
}

message GetEventGroupsResponse {
  repeated EventGroup groups = 1;
}

message DeleteEventsRequest {
  int64 stream_id = 1;
  int32 pid = 2;
  int64 group_id = 3;
  Event.Kind kind = 4;
  // Include events from timestamp (inclusive)
  int64 from_timestamp = 5;
  // Include events to timestamp (inclusive)
  int64 to_timestamp = 6;
}

message DeleteEventsResponse {
}

// An event group is a collection of events that share the same group_id.
// The events in a group should have the same |session_id| and |kind|.
message EventGroup {
  int64 group_id = 1;
  repeated Event events = 2;
}

// Proto used for configuring the daemon.
// The message itself is created and pushed to device from Studio
// and can be access via profiler::Config::Instance().
message DaemonConfig {
  message CpuConfig {
    // Waiting time in Seconds for ART when stopping the ongoing ART profiling.
    int32 art_stop_timeout_sec = 1;
    // equivalent to StudioFlags.PROFILER_USE_PERFETTO
    bool use_perfetto = 2 [deprecated = true];
  }
  message LayoutInspectorConfig {
    // equivalent to StudioFlags.LAYOUT_INSPECTOR_AUTOCONNECT_ENABLED
    bool autoconnect_enabled = 1;
  }
  CommonConfig common = 1;
  CpuConfig cpu = 2;
  LayoutInspectorConfig layout_inspector_config = 3;
}