1 /* 2 * Copyright (C) 2019 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 package com.android.internal.logging; 18 19 import android.annotation.NonNull; 20 import android.annotation.Nullable; 21 22 /** 23 * Logging interface for UI events. Normal implementation is UiEventLoggerImpl. 24 * For testing, use fake implementation UiEventLoggerFake. 25 * 26 * See go/sysui-event-logs and UiEventReported atom in atoms.proto. 27 */ 28 public interface UiEventLogger { 29 /** Put your Event IDs in enums that implement this interface, and document them using the 30 * UiEventEnum annotation. 31 * Event IDs must be globally unique. This will be enforced by tooling (forthcoming). 32 * OEMs should use event IDs above 100000 and below 1000000 (1 million). 33 */ 34 interface UiEventEnum { 35 36 /** 37 * Tag used to request new UI Event IDs via presubmit analysis. 38 * 39 * <p>Use RESERVE_NEW_UI_EVENT_ID as the constructor parameter for a new {@link EventEnum} 40 * to signal the presubmit analyzer to reserve a new ID for the event. The new ID will be 41 * returned as a Gerrit presubmit finding. Do not submit {@code RESERVE_NEW_UI_EVENT_ID} as 42 * the constructor parameter for any event. 43 * 44 * <pre> 45 * @UiEvent(doc = "Briefly describe the interaction when this event will be logged") 46 * UNIQUE_EVENT_NAME(RESERVE_NEW_UI_EVENT_ID); 47 * </pre> 48 */ 49 int RESERVE_NEW_UI_EVENT_ID = Integer.MIN_VALUE; // Negative IDs are ignored by the logger. 50 getId()51 int getId(); 52 } 53 54 /** 55 * Log a simple event, with no package information. Does nothing if event.getId() <= 0. 56 * @param event an enum implementing UiEventEnum interface. 57 */ log(@onNull UiEventEnum event)58 void log(@NonNull UiEventEnum event); 59 60 /** 61 * Log a simple event with an instance id, without package information. 62 * Does nothing if event.getId() <= 0. 63 * @param event an enum implementing UiEventEnum interface. 64 * @param instance An identifier obtained from an InstanceIdSequence. If null, reduces to log(). 65 */ log(@onNull UiEventEnum event, @Nullable InstanceId instance)66 void log(@NonNull UiEventEnum event, @Nullable InstanceId instance); 67 68 /** 69 * Log an event with package information. Does nothing if event.getId() <= 0. 70 * Give both uid and packageName if both are known, but one may be omitted if unknown. 71 * @param event an enum implementing UiEventEnum interface. 72 * @param uid the uid of the relevant app, if known (0 otherwise). 73 * @param packageName the package name of the relevant app, if known (null otherwise). 74 */ log(@onNull UiEventEnum event, int uid, @Nullable String packageName)75 void log(@NonNull UiEventEnum event, int uid, @Nullable String packageName); 76 77 /** 78 * Log an event with package information and an instance ID. 79 * Does nothing if event.getId() <= 0. 80 * @param event an enum implementing UiEventEnum interface. 81 * @param uid the uid of the relevant app, if known (0 otherwise). 82 * @param packageName the package name of the relevant app, if known (null otherwise). 83 * @param instance An identifier obtained from an InstanceIdSequence. If null, reduces to log(). 84 */ logWithInstanceId(@onNull UiEventEnum event, int uid, @Nullable String packageName, @Nullable InstanceId instance)85 void logWithInstanceId(@NonNull UiEventEnum event, int uid, @Nullable String packageName, 86 @Nullable InstanceId instance); 87 88 /** 89 * Log an event with ranked-choice information along with package. 90 * Does nothing if event.getId() <= 0. 91 * @param event an enum implementing UiEventEnum interface. 92 * @param uid the uid of the relevant app, if known (0 otherwise). 93 * @param packageName the package name of the relevant app, if known (null otherwise). 94 * @param position the position picked. 95 */ logWithPosition(@onNull UiEventEnum event, int uid, @Nullable String packageName, int position)96 void logWithPosition(@NonNull UiEventEnum event, int uid, @Nullable String packageName, 97 int position); 98 99 /** 100 * Log an event with ranked-choice information along with package and instance ID. 101 * Does nothing if event.getId() <= 0. 102 * @param event an enum implementing UiEventEnum interface. 103 * @param uid the uid of the relevant app, if known (0 otherwise). 104 * @param packageName the package name of the relevant app, if known (null otherwise). 105 * @param instance An identifier obtained from an InstanceIdSequence. If null, reduces to 106 * logWithPosition(). 107 * @param position the position picked. 108 */ logWithInstanceIdAndPosition(@onNull UiEventEnum event, int uid, @Nullable String packageName, @Nullable InstanceId instance, int position)109 void logWithInstanceIdAndPosition(@NonNull UiEventEnum event, int uid, 110 @Nullable String packageName, @Nullable InstanceId instance, int position); 111 } 112