1 /*
2  * Copyright (C) 2023 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.devicelockcontroller.stats;
18 
19 import androidx.annotation.IntDef;
20 
21 import com.android.devicelockcontroller.DevicelockStatsLog;
22 
23 import java.lang.annotation.Retention;
24 import java.lang.annotation.RetentionPolicy;
25 
26 /**
27  * Utility class wrapping operations related to Statistics.
28  *
29  * Please refer to {@link DevicelockStatsLog} class and
30  * stats/atoms/devicelock/devicelock_extension_atoms.proto for more information.
31  */
32 public interface StatsLogger {
33     /**
34      * Logs the analytics event of attempting to get device check in status from the server,
35      * regardless if the result is successful.
36      */
logGetDeviceCheckInStatus()37     void logGetDeviceCheckInStatus();
38 
39     /**
40      * Logs the analytics event of successfully pausing the device provisioning.
41      */
logPauseDeviceProvisioning()42     void logPauseDeviceProvisioning();
43 
44     /**
45      * Logs the analytics event of successfully reporting the device provisioning state to the
46      * server.
47      */
logReportDeviceProvisionState()48     void logReportDeviceProvisionState();
49 
50     /**
51      * Logs the analytics event of receiving a result from the server of the
52      * IsDeviceInApprovedCountry gRPC call.
53      */
logIsDeviceInApprovedCountry()54     void logIsDeviceInApprovedCountry();
55 
56     /**
57      * Logs the analytics event of receiving a request from the Kisok app.
58      *
59      * @param uid The UID of the Kiosk app, which can be acquired from the PackageManager.
60      */
logKioskAppRequest(int uid)61     void logKioskAppRequest(int uid);
62 
63     /**
64      * Logs the analytics event of starting the provisioning process, starting the Kiosk app, and
65      * the time elapsed in between.
66      */
logProvisioningComplete(long timeSpentInProvisioningMillis)67     void logProvisioningComplete(long timeSpentInProvisioningMillis);
68 
69     /**
70      * Logs the analytics event of resetting the device due to a failed provisioning.
71      *
72      * @param isProvisioningMandatory True if the provision is mandatory, false otherwise.
73      */
logDeviceReset(boolean isProvisioningMandatory)74     void logDeviceReset(boolean isProvisioningMandatory);
75 
76     /**
77      * Logs the analytics event of successfully handling a check in response received from the
78      * server.
79      */
logSuccessfulCheckIn()80     void logSuccessfulCheckIn();
81 
82     /**
83      * Logs the analytics event of successfully completing the provisioning.
84      */
logSuccessfulProvisioning()85     void logSuccessfulProvisioning();
86 
87     /**
88      * Logs the analytics event of retrying a check in request.
89      *
90      * @param reason The reason of the retry, the enum corresponds to the RetryReason in
91      *               frameworks/proto_logging/stats/atoms/devicelock/
92      *               devicelock_extension_atoms.proto
93      */
logCheckInRetry(@heckInRetryReason int reason)94     void logCheckInRetry(@CheckInRetryReason int reason);
95 
96     // TODO(bojiandu): update this definition after updating the atom to match the new design
97     @Retention(RetentionPolicy.SOURCE)
98     @IntDef({
99             CheckInRetryReason.RESPONSE_UNSPECIFIED,
100             CheckInRetryReason.CONFIG_UNAVAILABLE,
101             CheckInRetryReason.NETWORK_TIME_UNAVAILABLE,
102             CheckInRetryReason.RPC_FAILURE
103     })
104     @interface CheckInRetryReason {
105         int RESPONSE_UNSPECIFIED = 0;
106         int CONFIG_UNAVAILABLE = 1;
107         int NETWORK_TIME_UNAVAILABLE = 2;
108         int RPC_FAILURE = 3;
109     }
110 
111     /**
112      * Logs the analytics event of a provision failure.
113      *
114      * @param reason The reason of the failure, the enum corresponds to the FailureReason in
115      *               frameworks/proto_logging/stats/atoms/devicelock/
116      *               devicelock_extension_atoms.proto
117      */
logProvisionFailure(@rovisionFailureReasonStats int reason)118     void logProvisionFailure(@ProvisionFailureReasonStats int reason);
119 
120     @Retention(RetentionPolicy.SOURCE)
121     @IntDef({
122             ProvisionFailureReasonStats.UNKNOWN,
123             ProvisionFailureReasonStats.PLAY_TASK_UNAVAILABLE,
124             ProvisionFailureReasonStats.PLAY_INSTALLATION_FAILED,
125             ProvisionFailureReasonStats.COUNTRY_INFO_UNAVAILABLE,
126             ProvisionFailureReasonStats.NOT_IN_ELIGIBLE_COUNTRY,
127             ProvisionFailureReasonStats.POLICY_ENFORCEMENT_FAILED
128     })
129     @interface ProvisionFailureReasonStats {
130         // Unknown reason
131         int UNKNOWN = 0;
132         // Failed due to play task unavailable
133         int PLAY_TASK_UNAVAILABLE = 1;
134         // Failed due to installation from play unsuccessful
135         int PLAY_INSTALLATION_FAILED = 2;
136         // Failed due to country eligibility unknown
137         int COUNTRY_INFO_UNAVAILABLE = 3;
138         // Failed due to country not eligible
139         int NOT_IN_ELIGIBLE_COUNTRY = 4;
140         // Failed due to unable to enforce policies
141         int POLICY_ENFORCEMENT_FAILED = 5;
142     }
143 
144     /**
145      * Logs the analytics event of a lock device failure.
146      *
147      * @param deviceStatePostCommand The device state after the lock device command
148      */
logLockDeviceFailure(@eviceStateStats int deviceStatePostCommand)149     void logLockDeviceFailure(@DeviceStateStats int deviceStatePostCommand);
150 
151     /**
152      * Logs the analytics event of a unlock device failure.
153      *
154      * @param deviceStatePostCommand The device state after the unlock device command
155      */
logUnlockDeviceFailure(@eviceStateStats int deviceStatePostCommand)156     void logUnlockDeviceFailure(@DeviceStateStats int deviceStatePostCommand);
157 
158     @Retention(RetentionPolicy.SOURCE)
159     @IntDef({
160             DeviceStateStats.UNDEFINED,
161             DeviceStateStats.UNLOCKED,
162             DeviceStateStats.LOCKED,
163             DeviceStateStats.CLEARED,
164     })
165     @interface DeviceStateStats {
166         int UNDEFINED = 0;
167         int UNLOCKED = 1;
168         int LOCKED = 2;
169         int CLEARED = 3;
170     }
171 
172     /**
173      * Logs the analytics event of successfully locking the device.
174      */
logSuccessfulLockingDevice()175     void logSuccessfulLockingDevice();
176 
177     /**
178      * Logs the analytics event of successfully unlocking the device.
179      */
logSuccessfulUnlockingDevice()180     void logSuccessfulUnlockingDevice();
181 }
182