service/src/com/android/car/telemetry/proto/telemetry.proto

/*
 * Copyright (C) 2021 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 = "proto2";

package android.car.telemetry;

option java_package = "com.android.car.telemetry";
option java_outer_classname = "TelemetryProto";

// A metrics configuration.
//
// The metrics configuration describes a metric that is collected from a device.
// It includes a declarative part that configures the metric and the data publisher
// and a data handler to process the data and create a statistic.
// The latter is written in Lua language.
message MetricsConfig {
  // Required.
  // The name of the configuration. Must be unique within a device.
  //
  // Changing the name of the config should be done carefully, by first removing the config
  // with the old name, and creating a new config with a new name.
  // The name is used to for persisting the configs and other internal state, not removing the
  // configs with old name will result dangling data in the system.
  //
  // Only alphanumeric and _ characters are allowed. Minimum length is 3 chars.
  optional string name = 1;

  // Required.
  // Version number of the configuration. Must be more than 0.
  optional int32 version = 2;

  // Required.
  // A script that is executed at the device side. Must contain all the handler
  // functions defined in the listeners below.
  // The script functions must be `pure` functions.
  optional string script = 3;

  // Required.
  repeated Subscriber subscribers = 4;
}

// Parameters for Vehicle Properties publisher.
// See https://source.android.com/devices/automotive/vhal/properties
message VehiclePropertyPublisher {
  // Required.
  // See packages/services/Car/car-lib/src/android/car/VehiclePropertyIds.java
  optional int32 vehicle_property_id = 1;

  // See
  // packages/services/Car/car-lib/src/android/car/hardware/property/CarPropertyManager.java
  // look for constants SENSOR_RATE_*;
  optional float read_rate = 2;
}

// Parameters for cartelemetryd publisher.
// See packages/services/Car/cpp/telemetry for CarData proto and docs.
message CarTelemetrydPublisher {
  // Required.
  // CarData id to subscribe to.
  // See packages/services/Car/cpp/telemetry/proto/CarData.proto for all the
  // messages and IDs.
  optional int32 id = 1;
}

// Publisher for various system metrics and stats.
// It pushes metrics to the subscribers periodically or when garage mode starts.
message StatsPublisher {
  enum SystemMetric {
    UNDEFINED = 0;  // default value, not used
    // Collects all the app start events with the initial used RSS/CACHE/SWAP memory.
    APP_START_MEMORY_STATE_CAPTURED = 1;
    // Collects memory state of processes in 5-minute buckets (1 memory measurement per bucket).
    PROCESS_MEMORY_STATE = 2;
    // Collects activity foreground/background transition events.
    ACTIVITY_FOREGROUND_STATE_CHANGED = 3;
    // Collects process CPU usage time.
    PROCESS_CPU_TIME = 4;
    // Collects app crash events.
    APP_CRASH_OCCURRED = 5;
    // Collects App Not Responding events.
    ANR_OCCURRED = 6;
    // Collects "wtf"-level log events.
    WTF_OCCURRED = 7;
  }

  // Required.
  // System metric for the publisher.
  optional SystemMetric system_metric = 1;
}

// Publisher for connectivity stats.
// It pulls connectivity metrics every 1 minute (configurable via android
// properties).
// TODO(b/197905656): pull netstats when driving session changes.
message ConnectivityPublisher {
  // Transports are from android.net.NetworkCapabilities.
  enum Transport {
    TRANSPORT_UNDEFINED = 0;  // default value, not used
    TRANSPORT_CELLULAR = 1;
    TRANSPORT_WIFI = 2;
    TRANSPORT_BLUETOOTH = 3;
    TRANSPORT_ETHERNET = 4;
  }

  enum OemType {
    OEM_UNDEFINED = 0;  // default value, not used
    OEM_NONE = 1;       // non-OEM networks only
    OEM_MANAGED = 2;    // OEM managed networks only
  }

  // Required. Network transport.
  optional Transport transport = 1;

  // Required. OEM network type.
  optional OemType oem_type = 2;
}

// Specifies data publisher and its parameters.
message Publisher {
  oneof publisher {
    VehiclePropertyPublisher vehicle_property = 1;
    CarTelemetrydPublisher cartelemetryd = 2;
    StatsPublisher stats = 3;
    ConnectivityPublisher connectivity = 4;
  }
}

// Specifies publisher with its parameters and the handler function that's invoked
// when data is received. The format of the data depends on the Publisher.
message Subscriber {
  // Required.
  // Name of the function that handles the published data. Must be defined
  // in the script.
  optional string handler = 1;

  // Required.
  // Publisher definition.
  optional Publisher publisher = 2;

  // Required.
  // Priority of the subscriber, which affects the order of when it receives data.
  // Ranges from 0 to 100. 0 being highest priority and 100 being lowest.
  optional int32 priority = 3;
}

// A message that encapsulates an error that's produced when collecting metrics.
// Any changes here should also be reflected on
// p/s/C/service/src/com/android/car/telemetry/scriptexecutorinterface/IScriptExecutorListener.aidl
// p/s/C/package/ScriptExecutor/src/ScriptExecutorListener.h
message TelemetryError {
  enum ErrorType {
    // Not used.
    UNSPECIFIED = 0;

    // Used when an error occurs in the ScriptExecutor code.
    SCRIPT_EXECUTOR_ERROR = 1;

    // Used when an error occurs while executing the Lua script (such as errors returned by
    // lua_pcall)
    LUA_RUNTIME_ERROR = 2;

    // Used to log errors by a script itself, for instance, when a script received inputs outside
    // of expected range.
    LUA_SCRIPT_ERROR = 3;
  }

  // Required.
  // A type that indicates the category of the error.
  optional ErrorType error_type = 1;

  // Required.
  // Human readable message explaining the error or how to fix it.
  optional string message = 2;

  // Optional.
  // If there is an exception, there will be stack trace. However this information is not always
  // available.
  optional string stack_trace = 3;
}