1/*
2 * Copyright (C) 2021 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17syntax = "proto2";
18
19package android.car.telemetry;
20
21option java_package = "com.android.car.telemetry";
22option java_outer_classname = "TelemetryProto";
23
24// A metrics configuration.
25//
26// The metrics configuration describes a metric that is collected from a device.
27// It includes a declarative part that configures the metric and the data publisher
28// and a data handler to process the data and create a statistic.
29// The latter is written in Lua language.
30message MetricsConfig {
31  // Required.
32  // The name of the configuration. Must be unique within a device.
33  //
34  // Changing the name of the config should be done carefully, by first removing the config
35  // with the old name, and creating a new config with a new name.
36  // The name is used to for persisting the configs and other internal state, not removing the
37  // configs with old name will result dangling data in the system.
38  //
39  // Only alphanumeric and _ characters are allowed. Minimum length is 3 chars.
40  optional string name = 1;
41
42  // Required.
43  // Version number of the configuration. Must be more than 0.
44  optional int32 version = 2;
45
46  // Required.
47  // A script that is executed at the device side. Must contain all the handler
48  // functions defined in the listeners below.
49  // The script functions must be `pure` functions.
50  optional string script = 3;
51
52  // Required.
53  repeated Subscriber subscribers = 4;
54}
55
56// Parameters for Vehicle Properties publisher.
57// See https://source.android.com/devices/automotive/vhal/properties
58message VehiclePropertyPublisher {
59  // Required.
60  // See packages/services/Car/car-lib/src/android/car/VehiclePropertyIds.java
61  optional int32 vehicle_property_id = 1;
62
63  // See
64  // packages/services/Car/car-lib/src/android/car/hardware/property/CarPropertyManager.java
65  // look for constants SENSOR_RATE_*;
66  optional float read_rate = 2;
67}
68
69// Parameters for cartelemetryd publisher.
70// See packages/services/Car/cpp/telemetry for CarData proto and docs.
71message CarTelemetrydPublisher {
72  // Required.
73  // CarData id to subscribe to.
74  // See packages/services/Car/cpp/telemetry/proto/CarData.proto for all the
75  // messages and IDs.
76  optional int32 id = 1;
77}
78
79// Publisher for various system metrics and stats.
80// It pushes metrics to the subscribers periodically or when garage mode starts.
81message StatsPublisher {
82  enum SystemMetric {
83    UNDEFINED = 0;  // default value, not used
84    // Collects all the app start events with the initial used RSS/CACHE/SWAP memory.
85    APP_START_MEMORY_STATE_CAPTURED = 1;
86    // Collects memory state of processes in 5-minute buckets (1 memory measurement per bucket).
87    PROCESS_MEMORY_STATE = 2;
88    // Collects activity foreground/background transition events.
89    ACTIVITY_FOREGROUND_STATE_CHANGED = 3;
90    // Collects process CPU usage time.
91    PROCESS_CPU_TIME = 4;
92    // Collects app crash events.
93    APP_CRASH_OCCURRED = 5;
94    // Collects App Not Responding events.
95    ANR_OCCURRED = 6;
96    // Collects "wtf"-level log events.
97    WTF_OCCURRED = 7;
98  }
99
100  // Required.
101  // System metric for the publisher.
102  optional SystemMetric system_metric = 1;
103}
104
105// Specifies data publisher and its parameters.
106message Publisher {
107  oneof publisher {
108    VehiclePropertyPublisher vehicle_property = 1;
109    CarTelemetrydPublisher cartelemetryd = 2;
110    StatsPublisher stats = 3;
111  }
112}
113
114// Specifies publisher with its parameters and the handler function that's invoked
115// when data is received. The format of the data depends on the Publisher.
116message Subscriber {
117  // Required.
118  // Name of the function that handles the published data. Must be defined
119  // in the script.
120  optional string handler = 1;
121
122  // Required.
123  // Publisher definition.
124  optional Publisher publisher = 2;
125
126  // Required.
127  // Priority of the subscriber, which affects the order of when it receives data.
128  // Ranges from 0 to 100. 0 being highest priority and 100 being lowest.
129  optional int32 priority = 3;
130}
131
132// A message that encapsulates an error that's produced when collecting metrics.
133// Any changes here should also be reflected on
134// p/s/C/service/src/com/android/car/telemetry/scriptexecutorinterface/IScriptExecutorListener.aidl
135// p/s/C/package/ScriptExecutor/src/ScriptExecutorListener.h
136message TelemetryError {
137  enum ErrorType {
138    // Not used.
139    UNSPECIFIED = 0;
140
141    // Used when an error occurs in the ScriptExecutor code.
142    SCRIPT_EXECUTOR_ERROR = 1;
143
144    // Used when an error occurs while executing the Lua script (such as errors returned by
145    // lua_pcall)
146    LUA_RUNTIME_ERROR = 2;
147
148    // Used to log errors by a script itself, for instance, when a script received inputs outside
149    // of expected range.
150    LUA_SCRIPT_ERROR = 3;
151  }
152
153  // Required.
154  // A type that indicates the category of the error.
155  optional ErrorType error_type = 1;
156
157  // Required.
158  // Human readable message explaining the error or how to fix it.
159  optional string message = 2;
160
161  // Optional.
162  // If there is an exception, there will be stack trace. However this information is not always
163  // available.
164  optional string stack_trace = 3;
165}
166