• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 
17 syntax = "proto2";
18 
19 package android.os.statsd;
20 option java_package = "com.android.os";
21 option java_multiple_files = true;
22 option java_outer_classname = "AtomFieldOptions";
23 
24 import "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 // }
66 message 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.
99 enum 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.
109 enum 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
118 message 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 
130 extend 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