1/*
2 * Copyright (C) 2018 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.os.statsd;
20option java_package = "com.android.os";
21option java_multiple_files = true;
22option java_outer_classname = "AtomFieldOptions";
23
24import "google/protobuf/descriptor.proto";
25
26// Used to annotate an atom that represents a state change. A state change atom must have exactly
27// ONE exclusive state field, and any number of primary key fields. For example, message
28// UidProcessStateChanged {
29//    optional int32 uid = 1 [(state_field_option).primary_field = true];
30//    optional android.app.ProcessStateEnum state =
31//            2 [(state_field_option).exclusive_state = true];
32//  }
33// Each UidProcessStateChanged atom event represents a state change for a specific uid.
34// A new state automatically overrides the previous state.
35//
36// If the atom has 2 or more primary fields, it means the combination of the
37// primary fields are the primary key.
38// For example:
39// message ThreadStateChanged {
40//    optional int32 pid = 1  [(state_field_option).primary_field = true];
41//    optional int32 tid = 2  [(state_field_option).primary_field = true];
42//    optional int32 state = 3 [(state_field_option).exclusive_state = true];
43// }
44//
45// Sometimes, there is no primary key field, when the state is GLOBAL.
46// For example,
47// message ScreenStateChanged {
48//    optional android.view.DisplayStateEnum state =
49//          1 [(state_field_option).exclusive_state = true];
50// }
51//
52// For state atoms with attribution chain, sometimes the primary key is the first uid in the chain.
53// For example:
54// message AudioStateChanged {
55//   repeated AttributionNode attribution_node = 1
56//       [(stateFieldOption).primary_field_first_uid = true];
57//
58//    enum State {
59//      OFF = 0;
60//      ON = 1;
61//      // RESET indicates all audio stopped. Used when it (re)starts (e.g. after it crashes).
62//      RESET = 2;
63//    }
64//    optional State state = 2 [(stateFieldOption).exclusive_state = true];
65// }
66message StateAtomFieldOption {
67    // Fields that represent the key that the state belongs to.
68    // Used on simple proto fields. Do not use on attribution chains.
69    optional bool primary_field = 1 [default = false];
70
71    // The field that represents the state. It's an exclusive state.
72    optional bool exclusive_state = 2 [default = false];
73
74    // Used on an attribution chain field to indicate that the first uid is the
75    // primary field.
76    optional bool primary_field_first_uid = 3 [default = false];
77
78    // Note: We cannot annotate directly on the enums because many enums are imported from other
79    // proto files in the platform. proto-lite cc library does not support annotations unfortunately
80
81    // Knowing the default state value allows state trackers to remove entries that become the
82    // default state. If there is no default value specified, the default value is unknown, and all
83    // states will be tracked in memory.
84    optional int32 default_state_value = 4;
85
86    // A reset state signals all states go to default value. For example, BLE reset means all active
87    // BLE scans are to be turned off.
88    optional int32 trigger_state_reset_value = 5;
89
90    // If the state change needs to count nesting. For example, given an exclusive_state field with
91    // possible states of OFF and ON, a sequence of N OFF events will require N ON events for the
92    // tracked state to change back to ON.
93    // Note: only valid for fields marked with exclusive_state where there are only 2 possible
94    // states.
95    optional bool nested = 6 [default = false];
96}
97
98// Used to generate StatsLog.write APIs.
99enum LogMode {
100    MODE_UNSET = 0;
101    // Log fields as their actual types e.g., all primary data types.
102    // Or fields that are hardcoded in stats_log_api_gen tool e.g., AttributionNode
103    MODE_AUTOMATIC = 1;
104    // Log fields in their proto binary format. These fields will not be parsed in statsd
105    MODE_BYTES = 2;
106}
107
108// Used to annotate an atom as belonging to a retriction category.
109enum RestrictionCategory {
110    RESTRICTION_UNSET = 0;
111    RESTRICTION_DIAGNOSTIC = 1;
112    RESTRICTION_SYSTEM_INTELLIGENCE = 2;
113    RESTRICTION_AUTHENTICATION = 3;
114    RESTRICTION_FRAUD_AND_ABUSE = 4;
115}
116
117// Options for restricting fields of atoms
118message FieldRestrictionOption {
119    optional bool peripheral_device_info = 1;
120    optional bool app_usage = 2;
121    optional bool app_activity = 3;
122    optional bool health_connect = 4;
123    optional bool accessibility = 5;
124    optional bool system_search = 6;
125    optional bool user_engagement = 7;
126    optional bool ambient_sensing = 8;
127    optional bool demographic_classification = 9;
128}
129
130extend google.protobuf.FieldOptions {
131    // Flags to decorate an atom that presents a state change.
132    optional StateAtomFieldOption state_field_option = 50000;
133
134    // Flags to decorate the uid fields in an atom.
135    optional bool is_uid = 50001 [default = false];
136
137    optional LogMode log_mode = 50002 [default = MODE_AUTOMATIC];
138
139    repeated string module = 50004;
140
141    optional bool truncate_timestamp = 50005 [default = false];
142
143    optional RestrictionCategory restriction_category = 50006;
144
145    optional FieldRestrictionOption field_restriction_option = 50007;
146}
147