profiler/proto/cpu.proto - platform/tools/base - Git at Google

 /*
  * 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 = "CpuProfiler";

 import "profiler.proto";

 service CpuService {
   rpc GetData(CpuDataRequest) returns (CpuDataResponse) {
   }


   rpc GetThreads(GetThreadsRequest) returns (GetThreadsResponse) {
   }

   rpc GetTraceInfo(GetTraceInfoRequest) returns (GetTraceInfoResponse) {
   }

   rpc GetTrace(GetTraceRequest) returns (GetTraceResponse) {
   }

   // Starts collecting execution metrics of a running app, such as usage info
   // and thread states. Does nothing if the app is already being monitored.
   // TODO(b/29258733): Support configuring sampling details.
   rpc StartMonitoringApp(CpuStartRequest) returns (CpuStartResponse) {
   }

   // Stops monitoring a running app. Does nothing if the app is not being
   // monitored, or is not running.
   rpc StopMonitoringApp(CpuStopRequest) returns (CpuStopResponse) {
   }

   // Starts recording app stacktraces of a running app.
   // Does nothing if the app is already being profiled with SimplePerf.
   // Returns an error if the app is already being profiled with ART.
   rpc StartProfilingApp(CpuProfilingAppStartRequest)
       returns (CpuProfilingAppStartResponse) {
   }

   // Stops recording app stacktraces of a running app. Does nothing if the app
   // is not being
   // profiled, or is not running.
   rpc StopProfilingApp(CpuProfilingAppStopRequest)
       returns (CpuProfilingAppStopResponse) {
   }
 }

 // Requests the state of all the threads in the given time range.
 message GetThreadsRequest {
   int32 app_id = 1;
   int64 start_timestamp = 2;
   int64 end_timestamp = 3;
 }

 // All the threads that exist in the requested range, and their
 // state changes during that period of time. If a thread was
 // alive at the beginning of the range, it will have its corresponding
 // state at that time.

 message GetThreadsResponse {
   // TODO: Once the other thread activity is gone, we can move this state to the right place.
   enum State {
     UNSPECIFIED = 0;
     RUNNING = 1;
     SLEEPING = 2;
     WAITING = 3;
     ZOMBIE = 4;
     STOPPED = 5;
     TRACING = 6;
     PAGING = 7;
     DEAD = 8;
     WAKEKILL = 9;
     WAKING = 10;
     PARKED = 11;
   }

   message ThreadActivity {
       int64 timestamp = 1;
       State new_state = 2;
   }

   message Thread {
     int32 tid = 1;
     string name = 2;
     repeated ThreadActivity activities = 3;
   }

   repeated Thread threads = 1;
 }

 // Requests all the traces that overlap with a time range.
 message GetTraceInfoRequest {
   int32 app_id = 1;
   int64 from_timestamp = 2; // inclusive
   int64 to_timestamp = 3; // inclusive
 }

 message GetTraceInfoResponse {
   repeated TraceInfo trace_info = 1;
 }

 // A TraceInfo contains the information regarding a trace
 // and should be returned if its time overlaps with the
 // one defined in a GetTraceInfoRequest.
 message TraceInfo {
   enum Profiler {
     UNSPECIFIED = 0;
     ART = 1;
     SIMPLE_PERF = 2;
   }
   Profiler profiler = 1;
   int64 from_timestamp = 2; // inclusive
   int64 to_timestamp = 3; // inclusive
   int32 trace_id = 4;
 }

 message GetTraceRequest {
   int32 app_id = 1;
   // Trace ID should be unique within an app.
   int32 trace_id = 2;
 }

 message GetTraceResponse {
   // TODO: add more status as needed.
   enum Status {
     UNSPECIFIED = 0;
     SUCCESS = 1;
     FAILURE = 2;
   }
   Status status = 1;
   bytes data = 2;
 }

 // Requests profiler data from the app with ID being |app_id|, in the time range
 // from |start_timestamp| (exclusive) to |end_timestamp| (inclusive), or
 // mathematically written as in interval (start_timestamp, end_timestamp].
 message CpuDataRequest {
   enum SpecialValues {
     // Protobuf requires the first enum value to be zero.
     UNSPECIFIED = 0;
     // A speical value used in |app_id| field to indicate the data of all apps
     // are requested.
     ANY_APP = -1;
   }
   int32 app_id = 1;  // Use |ANY_APP| if requesting the data of any apps.
   int64 start_timestamp = 2;  // Use -2^63 if no data is too old to return.
   int64 end_timestamp = 3;  // Use 2^63 - 1 if no data is too recent to return.
 }

 message CpuDataResponse {
   repeated CpuProfilerData data = 1;
 }

 message CpuStartRequest {
   int32 app_id = 1;
 }

 message CpuStartResponse {
   enum Status {
     UNSPECIFIED = 0;
     SUCCESS = 1;
     FAILURE_APP_NOT_RUNNING = 2;
     FAILURE_UNKNOWN = 3;
     FAILURE = 4;
   }
   Status status = 1;
 }

 message CpuStopRequest {
   int32 app_id = 1;
 }

 message CpuStopResponse {
   enum Status {
     UNSPECIFIED = 0;
     SUCCESS = 1;
     FAILURE_UNKNOWN = 2;
   }
   Status status = 1;
 }

 // Request profiling of app (identified by its package name |app_pkg_id|) to
 // start.
 // INSTRUMENTED is support only when ART is the profiler.
 message CpuProfilingAppStartRequest {
   string app_pkg_name = 1;
   enum Mode {
     UNSTATED = 0;
     SAMPLED = 1;
     INSTRUMENTED = 2;
   }
   enum Profiler {
     UNSPECIFIED = 0;
     ART = 1;
     SIMPLE_PERF = 2;
   }
   Mode mode = 2;
   Profiler profiler = 3;
 }

 // Returns the status and absolute path location (on device) where the trace
 // file will be written.
 message CpuProfilingAppStartResponse {
   enum Status {
     UNSPECIFIED = 0;
     SUCCESS = 1;
     FAILURE = 2;
   }
   Status status = 1;
   string error_message = 2;
 }

 // Request profiling of app (identified by its package name |app_pkg_id|) to
 // stop.
 message CpuProfilingAppStopRequest {
   string app_pkg_name = 1;
   enum Profiler {
     UNSPECIFIED = 0;
     ART = 1;
     SIMPLE_PERF = 2;
   }
   Profiler profiler = 2;
 }

 message CpuProfilingAppStopResponse {
   enum Status {
     UNSPECIFIED = 0;
     SUCCESS = 1;
     FAILURE = 2;
   }
   Status status = 1;
   string error_message = 2;
   // Trace ID should be unique within an app.
   int32 trace_id = 3;
   // TODO: remove this trace attribute after fully migrating to the new API.
   bytes trace = 4;
 }

 // CPU data of a given app process.
 message CpuProfilerData {
   CommonData basic_info = 1;
   oneof data {
     CpuUsageData cpu_usage = 2;
     ThreadActivities thread_activities = 3;
   }
 }

 // CPU usage data of an app process and the entire system at a given point.
 //
 // CPU usage data is most valuable when app data is combined with system data,
 // e.g., showing the CPU usage percentage number. One data consumer (e.g., an
 // Android Studio instance) would request an app's data, and another consumer
 // (e.g., another Android Studio instance) would request another app's. Both of
 // them need system data. Therefore, we put system data together with every
 // piece of app specific data.
 //
 // The absolute values of fields in this message are not very interesting.
 // The difference of two instances is more useful. It can show the system-
 // wide CPU utilization percentage and an app's CPU utilization percentage.
 // The values of the fields may overflow their type, but the usefulness stays
 // the same.
 message CpuUsageData {
   // Amount of time that this process has been using CPU, measured in
   // milliseconds.
   int64 app_cpu_time_in_millisec = 1;
   // Amount of time that the entire system (including applications) has been
   // using CPU, measured in milliseconds.
   int64 system_cpu_time_in_millisec = 2;
   // Amount of time since the system start, measured in milliseconds.
   int64 elapsed_time_in_millisec = 3;
 }

 // Thread activities, which is essentially changes in thread states.
 message ThreadActivities {
   repeated ThreadActivity activities = 1;
 }

 // A thread activity, which is essentially the change of a thread's state.
 message ThreadActivity {
   // TODO: Reduce the number of |State| values to exactly what we surface
   // to the user.
   enum State {
     UNSPECIFIED = 0;
     RUNNING = 1;
     SLEEPING = 2;
     WAITING = 3;
     ZOMBIE = 4;
     STOPPED = 5;
     TRACING = 6;
     PAGING = 7;
     DEAD = 8;
     WAKEKILL = 9;
     WAKING = 10;
     PARKED = 11;
   }
   int32 tid = 1;
   State new_state = 2;
   // Name of the thread.
   string name = 3;
   // Timestamp when the activity happens (or is detected).
   // Null means the timestamp of this activity is the same as the timestamp
   // as the |CpuProfilerData| message that includes this |TheadActivity|
   // message.
   int64 timestamp = 4;
 }
	/*
	* 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 = "CpuProfiler";

	import "profiler.proto";

	service CpuService {
	rpc GetData(CpuDataRequest) returns (CpuDataResponse) {
	}


	rpc GetThreads(GetThreadsRequest) returns (GetThreadsResponse) {
	}

	rpc GetTraceInfo(GetTraceInfoRequest) returns (GetTraceInfoResponse) {
	}

	rpc GetTrace(GetTraceRequest) returns (GetTraceResponse) {
	}

	// Starts collecting execution metrics of a running app, such as usage info
	// and thread states. Does nothing if the app is already being monitored.
	// TODO(b/29258733): Support configuring sampling details.
	rpc StartMonitoringApp(CpuStartRequest) returns (CpuStartResponse) {
	}

	// Stops monitoring a running app. Does nothing if the app is not being
	// monitored, or is not running.
	rpc StopMonitoringApp(CpuStopRequest) returns (CpuStopResponse) {
	}

	// Starts recording app stacktraces of a running app.
	// Does nothing if the app is already being profiled with SimplePerf.
	// Returns an error if the app is already being profiled with ART.
	rpc StartProfilingApp(CpuProfilingAppStartRequest)
	returns (CpuProfilingAppStartResponse) {
	}

	// Stops recording app stacktraces of a running app. Does nothing if the app
	// is not being
	// profiled, or is not running.
	rpc StopProfilingApp(CpuProfilingAppStopRequest)
	returns (CpuProfilingAppStopResponse) {
	}
	}

	// Requests the state of all the threads in the given time range.
	message GetThreadsRequest {
	int32 app_id = 1;
	int64 start_timestamp = 2;
	int64 end_timestamp = 3;
	}

	// All the threads that exist in the requested range, and their
	// state changes during that period of time. If a thread was
	// alive at the beginning of the range, it will have its corresponding
	// state at that time.

	message GetThreadsResponse {
	// TODO: Once the other thread activity is gone, we can move this state to the right place.
	enum State {
	UNSPECIFIED = 0;
	RUNNING = 1;
	SLEEPING = 2;
	WAITING = 3;
	ZOMBIE = 4;
	STOPPED = 5;
	TRACING = 6;
	PAGING = 7;
	DEAD = 8;
	WAKEKILL = 9;
	WAKING = 10;
	PARKED = 11;
	}

	message ThreadActivity {
	int64 timestamp = 1;
	State new_state = 2;
	}

	message Thread {
	int32 tid = 1;
	string name = 2;
	repeated ThreadActivity activities = 3;
	}

	repeated Thread threads = 1;
	}

	// Requests all the traces that overlap with a time range.
	message GetTraceInfoRequest {
	int32 app_id = 1;
	int64 from_timestamp = 2; // inclusive
	int64 to_timestamp = 3; // inclusive
	}

	message GetTraceInfoResponse {
	repeated TraceInfo trace_info = 1;
	}

	// A TraceInfo contains the information regarding a trace
	// and should be returned if its time overlaps with the
	// one defined in a GetTraceInfoRequest.
	message TraceInfo {
	enum Profiler {
	UNSPECIFIED = 0;
	ART = 1;
	SIMPLE_PERF = 2;
	}
	Profiler profiler = 1;
	int64 from_timestamp = 2; // inclusive
	int64 to_timestamp = 3; // inclusive
	int32 trace_id = 4;
	}

	message GetTraceRequest {
	int32 app_id = 1;
	// Trace ID should be unique within an app.
	int32 trace_id = 2;
	}

	message GetTraceResponse {
	// TODO: add more status as needed.
	enum Status {
	UNSPECIFIED = 0;
	SUCCESS = 1;
	FAILURE = 2;
	}
	Status status = 1;
	bytes data = 2;
	}

	// Requests profiler data from the app with ID being \|app_id\|, in the time range
	// from \|start_timestamp\| (exclusive) to \|end_timestamp\| (inclusive), or
	// mathematically written as in interval (start_timestamp, end_timestamp].
	message CpuDataRequest {
	enum SpecialValues {
	// Protobuf requires the first enum value to be zero.
	UNSPECIFIED = 0;
	// A speical value used in \|app_id\| field to indicate the data of all apps
	// are requested.
	ANY_APP = -1;
	}
	int32 app_id = 1; // Use \|ANY_APP\| if requesting the data of any apps.
	int64 start_timestamp = 2; // Use -2^63 if no data is too old to return.
	int64 end_timestamp = 3; // Use 2^63 - 1 if no data is too recent to return.
	}

	message CpuDataResponse {
	repeated CpuProfilerData data = 1;
	}

	message CpuStartRequest {
	int32 app_id = 1;
	}

	message CpuStartResponse {
	enum Status {
	UNSPECIFIED = 0;
	SUCCESS = 1;
	FAILURE_APP_NOT_RUNNING = 2;
	FAILURE_UNKNOWN = 3;
	FAILURE = 4;
	}
	Status status = 1;
	}

	message CpuStopRequest {
	int32 app_id = 1;
	}

	message CpuStopResponse {
	enum Status {
	UNSPECIFIED = 0;
	SUCCESS = 1;
	FAILURE_UNKNOWN = 2;
	}
	Status status = 1;
	}

	// Request profiling of app (identified by its package name \|app_pkg_id\|) to
	// start.
	// INSTRUMENTED is support only when ART is the profiler.
	message CpuProfilingAppStartRequest {
	string app_pkg_name = 1;
	enum Mode {
	UNSTATED = 0;
	SAMPLED = 1;
	INSTRUMENTED = 2;
	}
	enum Profiler {
	UNSPECIFIED = 0;
	ART = 1;
	SIMPLE_PERF = 2;
	}
	Mode mode = 2;
	Profiler profiler = 3;
	}

	// Returns the status and absolute path location (on device) where the trace
	// file will be written.
	message CpuProfilingAppStartResponse {
	enum Status {
	UNSPECIFIED = 0;
	SUCCESS = 1;
	FAILURE = 2;
	}
	Status status = 1;
	string error_message = 2;
	}

	// Request profiling of app (identified by its package name \|app_pkg_id\|) to
	// stop.
	message CpuProfilingAppStopRequest {
	string app_pkg_name = 1;
	enum Profiler {
	UNSPECIFIED = 0;
	ART = 1;
	SIMPLE_PERF = 2;
	}
	Profiler profiler = 2;
	}

	message CpuProfilingAppStopResponse {
	enum Status {
	UNSPECIFIED = 0;
	SUCCESS = 1;
	FAILURE = 2;
	}
	Status status = 1;
	string error_message = 2;
	// Trace ID should be unique within an app.
	int32 trace_id = 3;
	// TODO: remove this trace attribute after fully migrating to the new API.
	bytes trace = 4;
	}

	// CPU data of a given app process.
	message CpuProfilerData {
	CommonData basic_info = 1;
	oneof data {
	CpuUsageData cpu_usage = 2;
	ThreadActivities thread_activities = 3;
	}
	}

	// CPU usage data of an app process and the entire system at a given point.
	//
	// CPU usage data is most valuable when app data is combined with system data,
	// e.g., showing the CPU usage percentage number. One data consumer (e.g., an
	// Android Studio instance) would request an app's data, and another consumer
	// (e.g., another Android Studio instance) would request another app's. Both of
	// them need system data. Therefore, we put system data together with every
	// piece of app specific data.
	//
	// The absolute values of fields in this message are not very interesting.
	// The difference of two instances is more useful. It can show the system-
	// wide CPU utilization percentage and an app's CPU utilization percentage.
	// The values of the fields may overflow their type, but the usefulness stays
	// the same.
	message CpuUsageData {
	// Amount of time that this process has been using CPU, measured in
	// milliseconds.
	int64 app_cpu_time_in_millisec = 1;
	// Amount of time that the entire system (including applications) has been
	// using CPU, measured in milliseconds.
	int64 system_cpu_time_in_millisec = 2;
	// Amount of time since the system start, measured in milliseconds.
	int64 elapsed_time_in_millisec = 3;
	}

	// Thread activities, which is essentially changes in thread states.
	message ThreadActivities {
	repeated ThreadActivity activities = 1;
	}

	// A thread activity, which is essentially the change of a thread's state.
	message ThreadActivity {
	// TODO: Reduce the number of \|State\| values to exactly what we surface
	// to the user.
	enum State {
	UNSPECIFIED = 0;
	RUNNING = 1;
	SLEEPING = 2;
	WAITING = 3;
	ZOMBIE = 4;
	STOPPED = 5;
	TRACING = 6;
	PAGING = 7;
	DEAD = 8;
	WAKEKILL = 9;
	WAKING = 10;
	PARKED = 11;
	}
	int32 tid = 1;
	State new_state = 2;
	// Name of the thread.
	string name = 3;
	// Timestamp when the activity happens (or is detected).
	// Null means the timestamp of this activity is the same as the timestamp
	// as the \|CpuProfilerData\| message that includes this \|TheadActivity\|
	// message.
	int64 timestamp = 4;
	}