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 "cpu_data.proto";
import "network_data.proto";

message Event {
  enum Kind {
    NONE = 0;
    // group_id: stream id
    STREAM = 1;
    // group_id: process id
    PROCESS = 2;
    // No specified group_id, the latest event in a session is used.
    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;

    // Cpu Profiler Prefix = 300
    // group_id: process id
    CPU_USAGE = 301;
    // group_id: thread id
    CPU_THREAD = 302;

    // Memory Profiler Prefix = 400

    // Energy Profiler Prefix = 500

    // Event Profiler Prefix = 600
  }

  // 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
  }

  // 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;

  oneof union {
    StreamData stream = 6;
    ProcessData process = 7;
    AgentData agent_data = 8;

    // 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;

    // Cpu Profiler Prefix = 300
    CpuUsageData cpu_usage = 301;
    CpuThreadData cpu_thread = 302;

    // Memory Profiler Prefix = 400
    // Energy Profiler Prefix = 500
    // Event Profiler Prefix = 600
  }
}

// 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
  }

  // Special Android api levels that the profiler cares about.
  enum AndroidVersion {
    UNKNOWN = 0;
    O = 26; // First API where JVMTI is supported.
    P = 28;
  }

  // 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;
  State state = 11;
}

message Process {
  enum State {
    UNSPECIFIED = 0;
    ALIVE = 1;
    DEAD = 2;
  }
  // 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;
}

// 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;
  // Whether JVMTI live allocation is enabled for the session.
  bool live_allocation_enabled = 5;
  // Session's type which indicates what data it has.
  SessionType type = 6;
}

message Stream {
  // A list of supported stream types.
  enum Type {
    UNSPECIFIED_STREAM_TYPE = 0;
    DEVICE = 1;
  }
  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;
    // Whether JVMTI live allocation is enabled for the session.
    bool live_allocation_enabled = 8;
    // Session's type which indicates what data it has.
    SessionType type = 9;
  }

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

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

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;
}