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