transport/proto/common.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 = "Common";

import "app_inspection.proto";
import "cpu_data.proto";
import "echo.proto";
import "energy_data.proto";
import "interaction_data.proto";
import "memory_data.proto";
import "network_data.proto";
import "user_counter_data.proto";
import "layout_inspector.proto";


message Event {
  enum Kind {
    NONE = 0;
    // group_id: stream id
    STREAM = 1;
    // group_id: process id
    PROCESS = 2;
    // No specified group_id. All agent events belonging to the same stream and
    // process are inherently in one group.
    AGENT = 3;

    // Profilers Prefix = 100
    // Session is a profiler only concept.
    // group_id: session id
    SESSION = 101;

    // Network Profiler Prefix = 200
    // group_id: |NETWORK_TX| or |NETWORK_RX|
    NETWORK_SPEED = 201;
    // No specified group_id
    NETWORK_CONNECTION_COUNT = 202;
    // group_id: connection id
    NETWORK_HTTP_CONNECTION = 203;
    // group_id: connection id
    NETWORK_HTTP_THREAD = 204;
    // No specified group_id
    NETWORK_TYPE = 205;

    // Cpu Profiler Prefix = 300
    // group_id: process id
    CPU_USAGE = 301;
    // group_id: thread id
    CPU_THREAD = 302;
    // group_id: device id
    CPU_CORE_CONFIG = 303;
    // group_id:: trace id
    CPU_TRACE = 304;
    // group_id:: trace id (populated only if the trace record exists)
    CPU_TRACE_STATUS = 305;

    // Memory Profiler Prefix = 400
    // no specified group id.
    MEMORY_USAGE = 401;
    // no specified group id.
    MEMORY_GC = 402;
    // group_id: hprof id (timestamp)
    MEMORY_HEAP_DUMP = 403;
    // group_id: hprof id
    MEMORY_HEAP_DUMP_STATUS = 404;
    // no specified gropu id.
    MEMORY_ALLOC_SAMPLING = 405;
    // group_id: track id (start timestamp)
    MEMORY_ALLOC_TRACKING = 406;
    // group_id: track id
    MEMORY_ALLOC_TRACKING_STATUS = 407;
    // no specified group id.
    MEMORY_ALLOC_CONTEXTS = 408;
    // no specified group id.
    MEMORY_ALLOC_EVENTS = 409;
    // no specified group id.
    MEMORY_JNI_REF_EVENTS = 410;
    // no specified group id.
    MEMORY_ALLOC_STATS = 411;
    // group_id: capture id (start timestamp)
    MEMORY_NATIVE_SAMPLE_CAPTURE = 412;
    // group_id: capture id (start timestamp)
    MEMORY_NATIVE_SAMPLE_STATUS =  413;

    // Energy Profiler Prefix = 500
    // no specified group id.
    ENERGY_USAGE = 501;
    // group_id: event_id
    ENERGY_EVENT = 502;

    // Event Profiler Prefix = 600
    INTERACTION = 601;
    VIEW = 602;

    // Custom Event Visualization prefix = 700;
    USER_COUNTERS = 701;

    // Demo echo event = 1000
    ECHO = 1000;

    // Layout inspector prefix = 1100
    LAYOUT_INSPECTOR_FOREGROUND_PROCESS = 1101;
    LAYOUT_INSPECTOR_TRACKING_FOREGROUND_PROCESS_SUPPORTED = 1102;

    // App inspection prefix = 1200.
    APP_INSPECTION_EVENT = 1201;
    APP_INSPECTION_RESPONSE = 1202;
    // group_id: unique ID representing that payload
    APP_INSPECTION_PAYLOAD = 1203;
  }

  // Fixed ID for pre-determined EventGroup. Event.Type is reserved for data
  // types that contain multiple states. So we use these group Ids to categorize
  // data that belong to the same Event.kind.
  enum EventGroupIds {
    INVALID = 0;

    // Network Profiler Prefix = 100
    NETWORK_TX = 101; // for NETWORK_SPEED sent data
    NETWORK_RX = 102; // for NETWORK_SPEED received data

    // Cpu Profiler Prefix = 200

    // Memory Profiler Prefix = 300

    // Energy Profiler Prefix = 400

    // Event Profiler Prefix = 500

    // App inspection prefix = 1200
  }

  // The process the event belongs to.
  int32 pid = 1;

  // The id of the group this event belongs to. This is not unique, for concepts
  // that span across a range of time (network requests, threads, etc), they
  // will all share the same |group_id|.
  int64 group_id = 2;

  // The kind of event (a higher level grouping of events that belong to the
  // same area) Useful for queries such as "all the groups of "kind" SESSION.
  Event.Kind kind = 3;

  // Timestamp in device wall clock time (ns).
  int64 timestamp = 4;

  // Indicate whether the event group has ended. Note that the |group_id| can
  // be recycled afterwards within the same |Event.Kind|.
  bool is_ended = 5;

  // Id of the command that triggered the event.
  int32 command_id = 6;

  oneof union {
    // General tranport event prefix = 10
    StreamData stream = 10;
    ProcessData process = 11;
    AgentData agent_data = 12;

    // Profiler Prefix = 100
    SessionData session = 101;

    // Network Profiler Prefix = 200
    // Populated when |kind| is |NETWORK_SPEED|
    NetworkSpeedData network_speed = 201;
    // Populated when |kind| is |NETWORK_CONNECTION_COUNT|
    NetworkConnectionData network_connections = 202;
    // Populated when |kind| is |NETWORK_HTTP_CONNECTION|
    NetworkHttpConnectionData network_http_connection = 203;
    // Populated when |kind| is |NETWORK_HTTP_THREAD|
    NetworkHttpThreadData network_http_thread = 204;
    // Populated when |kind| is |NETWORK_TYPE|
    NetworkTypeData network_type = 205;

    // Cpu Profiler Prefix = 300
    CpuUsageData cpu_usage = 301;
    CpuThreadData cpu_thread = 302;
    CpuCoreConfigData cpu_core_config = 303;
    CpuTraceData cpu_trace = 304;
    CpuTraceStatusData cpu_trace_status = 305;

    // Memory Profiler Prefix = 400
    MemoryUsageData memory_usage = 401;
    MemoryGcData memory_gc = 402;
    MemoryHeapDumpData memory_heapdump = 403;
    MemoryHeapDumpStatusData memory_heapdump_status = 404;
    MemoryAllocSamplingData memory_alloc_sampling = 405;
    MemoryAllocTrackingData memory_alloc_tracking = 406;
    MemoryAllocTrackingStatusData memory_alloc_tracking_status = 407;
    MemoryAllocContextsData memory_alloc_contexts = 408;
    MemoryAllocEventsData memory_alloc_events = 409;
    MemoryJniRefData memory_jni_ref_events = 410;
    MemoryAllocStatsData memory_alloc_Stats = 411;
    MemoryNativeTrackingData memory_native_tracking_status = 412;
    MemoryNativeSampleData memory_native_sample = 413;

    // Energy Profiler Prefix = 500
    // Energy consumption calculated from CPU, network and location activities.
    // Populated when |kind| is |ENERGY_USAGE|.
    EnergyUsageData energy_usage = 501;
    // Energy-impacting system event, e.g. wake locks.
    // Populated when |kind| is |ENERGY_EVENT|.
    EnergyEventData energy_event = 502;

    // Event Profiler Prefix = 600
    InteractionData interaction = 601;
    ViewData view = 602;

    // Custom Event Visualization Prefix = 700;
    UserCounterData user_counters = 701;

    // Echo Event Prefix = 1000
    echo.EchoData echo = 1000;

    // Layout inspector prefix = 1100
    layout_inspector.ForegroundProcess layout_inspector_foreground_process = 1101;
    layout_inspector.TrackingForegroundProcessSupported layout_inspector_tracking_foreground_process_supported = 1102;

    // App inspection prefix = 1200;
    app_inspection.AppInspectionEvent app_inspection_event = 1201;
    app_inspection.AppInspectionResponse app_inspection_response = 1202;
    app_inspection.AppInspectionPayload app_inspection_payload = 1203;
  }
}

// Note that |Device| instance refers to a device (physical/emulator) associated
// with a particular boot. e.g. if the same device is started twice, they are
// considered two separate |Device| instances.
message Device {
  enum State {
    UNSPECIFIED = 0;
    ONLINE = 1;
    OFFLINE = 2;      // e.g. emulator that is turned off
    DISCONNECTED = 3; // e.g. unplugged
  }

  // Numeric representation of the device's |serial| and |boot_id| properties.
  // Used for quickly indexing the device instead of having to perform string
  // comparisons.
  int64 device_id = 1;
  string manufacturer = 2; // e.g. 'Google', 'Motorola'
  string model = 3;        // e.g. 'Nexus 5', 'Pixel XL'
  string serial = 4;       // unique ID for this device
  string version = 5;      // e.g. '5.1.1', '8.0.0'
  int32 api_level = 6;     // e.g. 19, 25
  // |feature_level| will either be the same as |api_level| or |api_level + 1|
  // if the current device is a preview version. Code should check against
  // |feature_level|, not |api_level|, to see if a feature is available in the
  // framework or not. If |feature_level != api_level|, then |codename| will
  // also be set.
  int32 feature_level = 7;
  string codename = 8; // Identifies preview versions by API letter (e.g. 'O'),
                       // or '' for release
  string boot_id = 9;  // unique ID regenerated each boot time
  bool is_emulator = 10;
  string build_tags = 11;  // property of IDevice.PROP_BUILD_TAGS
  string build_type = 12;  // property of IDevice.PROP_BUILD_TYPE
  string cpu_abi = 13;     // property of IDevice.PROP_DEVICE_CPU_ABI
  State state = 14;

  // Should only be set if the pipeline does not support the device.
  // e.g. pre-Lollipop devices.
  string unsupported_reason = 15;
}

message Process {
  enum State {
    UNSPECIFIED = 0;
    ALIVE = 1;
    DEAD = 2;
  }
  // Less to more
  enum ExposureLevel {
    UNKNOWN = 0;
    RELEASE = 1;
    PROFILEABLE = 2;
    DEBUGGABLE = 3;
  }
  // Full name of the Android application/service
  string name = 1;
  // App's PID. Note that this is actually an int16, but gRPC only provides
  // int32.
  int32 pid = 2;
  // References Device's |device_id| property.
  int64 device_id = 3;
  State state = 4;
  // The device time when this Process was first detected by the profiler.
  int64 start_timestamp_ns = 5;
  // e.g. 'arm', 'arm86', 'x86', 'x86_64'
  // Also see SdkConstans.CPU_ARCH_*
  string abi_cpu_arch = 6;
  ExposureLevel exposure_level = 7;
}

// A Session represents a range of profiling data for an app running on a
// device. While of course different apps or different devices will imply
// separate sessions, the same app on the same device can also be broken up
// into several sessions.
message Session {
  // ID uniquely identifying this session. This will be unique across devices.
  int64 session_id = 1;
  // The stream from which the session is created.
  int64 stream_id = 2;
  // The PID of the app. Note that this is actually an int16, but gRPC only
  // provides int32.
  int32 pid = 3;
  // Start timestamp in device wall clock time.(ns)
  int64 start_timestamp = 4;
  // End timestamp in device wall clock time. (ns)
  // If LLONG_MAX, the session is ongoing and hasn't ended yet.
  int64 end_timestamp = 5;
}

// TODO to be deprecated once we have moved completely over to the new data
// pipeline. The |SessionStarted| message already encapsulates the same data.
message SessionMetaData {
  enum SessionType {
    UNSPECIFIED = 0;
    FULL = 1;
    MEMORY_CAPTURE = 2;
    CPU_CAPTURE = 3;
  }
  // References Session's |session_id| field
  int64 session_id = 1;
  // Session start time (unix epoch) as provided by the BeginSessionRequest.
  // For Studio-side display only.
  int64 start_timestamp_epoch_ms = 2;
  // Session name as provided by the BeginSessionRequest.
  // For Studio-side display only.
  string session_name = 3;
  // Whether JVMTI is used for the session
  bool jvmti_enabled = 4;
  // Session's type which indicates what data it has.
  SessionType type = 6;
  // See SdkConstans.CPU_ARCH_* as provided by the BeginSessionRequest.
  string process_abi = 7;
}

message Stream {
  // A list of supported stream types.
  enum Type {
    UNSPECIFIED_STREAM_TYPE = 0;
    DEVICE = 1;
    FILE = 2;
  }
  int64 stream_id = 1;
  Type type = 2;
  oneof union { Device device = 3; }
}

message StreamData {
  message StreamConnected { Stream stream = 1; }

  oneof union {
    StreamConnected stream_connected = 1;
    // Note - the disconnected event contains no payload.
  }
}

message ProcessData {
  message ProcessStarted { Process process = 1; }

  oneof union {
    ProcessStarted process_started = 1;
    // Note - the ended event contains no payload.
  }
}

message SessionData {
  message SessionStarted {
    // The session type here maps directly to the SessionMetadata.SessionType.
    // After the move to the new pipeline we can remove SessionMetadata.
    enum SessionType {
      UNSPECIFIED = 0;
      FULL = 1;
      MEMORY_CAPTURE = 2;
      CPU_CAPTURE = 3;
    }

    // References Session's |session_id| field
    int64 session_id = 1;
    // The stream from which the session is created.
    int64 stream_id = 2;
    // The PID of the app. Note that this is actually an int16, but gRPC only
    // provides int32.
    int32 pid = 3;
    // Session start time (unix epoch) as provided by the BeginSessionRequest.
    // For Studio-side display only.
    int64 start_timestamp_epoch_ms = 4;
    // Session name as provided by the BeginSessionRequest.
    // For Studio-side display only.
    string session_name = 5;
    // Whether JVMTI is used for the session
    bool jvmti_enabled = 6;
    // Session's type which indicates what data it has.
    SessionType type = 9;
    // See SdkConstans.CPU_ARCH_*
    string process_abi = 10;
  }

  oneof union {
    SessionStarted session_started = 1;
    // Note - the ended event contains no payload.
  }
}

message AgentData {
  enum Status {
    // Used when we don't know if the app is attachable or not.
    UNSPECIFIED = 0;
    // Set when the agent has attached to the application at least once.
    ATTACHED = 1;
    // Set when the application is determined to be unattachable.
    UNATTACHABLE = 2;
  }
  Status status = 1;
}

// Shared by both DaemonConfig and AgentConfig
message CommonConfig {
  enum SocketType {
    UNSPECIFIED_SOCKET = 0;
    ABSTRACT_SOCKET = 1;
  }

  // Which socket type we are using when setting up our service
  // if the device is O+ we use service_socket_name and
  // ABSTRACT_SOCKET. If the device is pre O we use
  // UNSPECIFIED_SOCKET and use the service_address.
  SocketType socket_type = 1;
  // address used for legacy devices (Nougat or older).
  string service_address = 2;
  // address used for jvmti devices that use unix sockets.
  string service_socket_name = 3;
  // equivalent to StudioFlags.PROFILER_ENERGY_PROFILER_ENABLED.
  bool energy_profiler_enabled = 4;
  // equivalent to StudioFlags.PROFILER_UNIFIED_PIPELINE
  bool profiler_unified_pipeline = 5;
  // equivalent to StudioFlags.PROFILER_CUSTOM_EVENT_VISUALIZATION
  bool profiler_custom_event_visualization = 6;
}