1 //
2 // Copyright (C) 2014 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 #ifndef UPDATE_ENGINE_METRICS_H_
18 #define UPDATE_ENGINE_METRICS_H_
19 
20 #include <base/time/time.h>
21 
22 #include "update_engine/certificate_checker.h"
23 #include "update_engine/common/constants.h"
24 #include "update_engine/common/error_code.h"
25 
26 namespace chromeos_update_engine {
27 
28 class SystemState;
29 
30 namespace metrics {
31 
32 // UpdateEngine.Daily.* metrics.
33 extern const char kMetricDailyOSAgeDays[];
34 
35 // UpdateEngine.Check.* metrics.
36 extern const char kMetricCheckDownloadErrorCode[];
37 extern const char kMetricCheckReaction[];
38 extern const char kMetricCheckResult[];
39 extern const char kMetricCheckTimeSinceLastCheckMinutes[];
40 extern const char kMetricCheckTimeSinceLastCheckUptimeMinutes[];
41 
42 // UpdateEngine.Attempt.* metrics.
43 extern const char kMetricAttemptNumber[];
44 extern const char kMetricAttemptPayloadType[];
45 extern const char kMetricAttemptPayloadSizeMiB[];
46 extern const char kMetricAttemptConnectionType[];
47 extern const char kMetricAttemptDurationMinutes[];
48 extern const char kMetricAttemptDurationUptimeMinutes[];
49 extern const char kMetricAttemptTimeSinceLastAttemptSeconds[];
50 extern const char kMetricAttemptTimeSinceLastAttemptUptimeSeconds[];
51 extern const char kMetricAttemptPayloadBytesDownloaded[];
52 extern const char kMetricAttemptPayloadDownloadSpeedKBps[];
53 extern const char kMetricAttemptDownloadSource[];
54 extern const char kMetricAttemptResult[];
55 extern const char kMetricAttemptInternalErrorCode[];
56 extern const char kMetricAttemptDownloadErrorCode[];
57 
58 // UpdateEngine.SuccessfulUpdate.* metrics.
59 extern const char kMetricSuccessfulUpdateAttemptCount[];
60 extern const char kMetricSuccessfulUpdateBytesDownloadedMiB[];
61 extern const char kMetricSuccessfulUpdateDownloadOverheadPercentage[];
62 extern const char kMetricSuccessfulUpdateDownloadSourcesUsed[];
63 extern const char kMetricSuccessfulUpdatePayloadType[];
64 extern const char kMetricSuccessfulUpdatePayloadSizeMiB[];
65 extern const char kMetricSuccessfulUpdateTotalDurationMinutes[];
66 extern const char kMetricSuccessfulUpdateRebootCount[];
67 extern const char kMetricSuccessfulUpdateUpdatesAbandonedCount[];
68 extern const char kMetricSuccessfulUpdateUrlSwitchCount[];
69 
70 // UpdateEngine.Rollback.* metric.
71 extern const char kMetricRollbackResult[];
72 
73 // UpdateEngine.* metrics.
74 extern const char kMetricFailedUpdateCount[];
75 extern const char kMetricInstallDateProvisioningSource[];
76 extern const char kMetricTimeToRebootMinutes[];
77 
78 // The possible outcomes when checking for updates.
79 //
80 // This is used in the UpdateEngine.Check.Result histogram.
81 enum class CheckResult {
82   kUpdateAvailable,    // Response indicates an update is available.
83   kNoUpdateAvailable,  // Response indicates no updates are available.
84   kDownloadError,      // Error downloading response from Omaha.
85   kParsingError,       // Error parsing response.
86   kRebootPending,      // No update check was performed a reboot is pending.
87 
88   kNumConstants,
89   kUnset = -1
90 };
91 
92 // Possible ways a device can react to a new update being available.
93 //
94 // This is used in the UpdateEngine.Check.Reaction histogram.
95 enum class CheckReaction {
96   kUpdating,    // Device proceeds to download and apply update.
97   kIgnored  ,   // Device-policy dictates ignoring the update.
98   kDeferring,   // Device-policy dictates waiting.
99   kBackingOff,  // Previous errors dictates waiting.
100 
101   kNumConstants,
102   kUnset = -1
103 };
104 
105 // The possible ways that downloading from a HTTP or HTTPS server can fail.
106 //
107 // This is used in the UpdateEngine.Check.DownloadErrorCode and
108 // UpdateEngine.Attempt.DownloadErrorCode histograms.
109 enum class DownloadErrorCode {
110   // Errors that can happen in the field. See http://crbug.com/355745
111   // for how we plan to add more detail in the future.
112   kDownloadError = 0,  // Error downloading data from server.
113 
114   // IMPORTANT: When adding a new error code, add at the bottom of the
115   // above block and before the kInputMalformed field. This
116   // is to ensure that error codes are not reordered.
117 
118   // This error code is used to convey that malformed input was given
119   // to the utils::GetDownloadErrorCode() function. This should never
120   // happen but if it does it's because of an internal update_engine
121   // error and we're interested in knowing this.
122   kInputMalformed = 100,
123 
124   // Bucket for capturing HTTP status codes not in the 200-599
125   // range. This should never happen in practice but if it does we
126   // want to know.
127   kHttpStatusOther = 101,
128 
129   // Above 200 and below 600, the value is the HTTP status code.
130   kHttpStatus200 = 200,
131 
132   kNumConstants = 600,
133 
134   kUnset = -1
135 };
136 
137 // Possible ways an update attempt can end.
138 //
139 // This is used in the UpdateEngine.Attempt.Result histogram.
140 enum class AttemptResult {
141   kUpdateSucceeded,             // The update succeeded.
142   kInternalError,               // An internal error occurred.
143   kPayloadDownloadError,        // Failure while downloading payload.
144   kMetadataMalformed,           // Metadata was malformed.
145   kOperationMalformed,          // An operation was malformed.
146   kOperationExecutionError,     // An operation failed to execute.
147   kMetadataVerificationFailed,  // Metadata verification failed.
148   kPayloadVerificationFailed,   // Payload verification failed.
149   kVerificationFailed,          // Root or Kernel partition verification failed.
150   kPostInstallFailed,           // The postinstall step failed.
151   kAbnormalTermination,         // The attempt ended abnormally.
152   kUpdateCanceled,              // Update canceled by the user.
153 
154   kNumConstants,
155 
156   kUnset = -1
157 };
158 
159 // Possible ways the device is connected to the Internet.
160 //
161 // This is used in the UpdateEngine.Attempt.ConnectionType histogram.
162 enum class ConnectionType {
163   kUnknown,           // Unknown.
164   kEthernet,          // Ethernet.
165   kWifi,              // Wireless.
166   kWimax,             // WiMax.
167   kBluetooth,         // Bluetooth.
168   kCellular,          // Cellular.
169   kTetheredEthernet,  // Tethered (Ethernet).
170   kTetheredWifi,      // Tethered (Wifi).
171 
172   kNumConstants,
173   kUnset = -1
174 };
175 
176 // Possible ways a rollback can end.
177 //
178 // This is used in the UpdateEngine.Rollback histogram.
179 enum class RollbackResult {
180   kFailed,
181   kSuccess,
182 
183   kNumConstants
184 };
185 
186 // Helper function to report metrics related to rollback. The
187 // following metrics are reported:
188 //
189 //  |kMetricRollbackResult|
190 void ReportRollbackMetrics(SystemState *system_state,
191                            RollbackResult result);
192 
193 // Helper function to report metrics reported once a day. The
194 // following metrics are reported:
195 //
196 //  |kMetricDailyOSAgeDays|
197 void ReportDailyMetrics(SystemState *system_state,
198                         base::TimeDelta os_age);
199 
200 // Helper function to report metrics after completing an update check
201 // with the ChromeOS update server ("Omaha"). The following metrics
202 // are reported:
203 //
204 //  |kMetricCheckResult|
205 //  |kMetricCheckReaction|
206 //  |kMetricCheckDownloadErrorCode|
207 //  |kMetricCheckTimeSinceLastCheckMinutes|
208 //  |kMetricCheckTimeSinceLastCheckUptimeMinutes|
209 //
210 // The |kMetricCheckResult| metric will only be reported if |result|
211 // is not |kUnset|.
212 //
213 // The |kMetricCheckReaction| metric will only be reported if
214 // |reaction| is not |kUnset|.
215 //
216 // The |kMetricCheckDownloadErrorCode| will only be reported if
217 // |download_error_code| is not |kUnset|.
218 //
219 // The values for the |kMetricCheckTimeSinceLastCheckMinutes| and
220 // |kMetricCheckTimeSinceLastCheckUptimeMinutes| metrics are
221 // automatically reported and calculated by maintaining persistent
222 // and process-local state variables.
223 void ReportUpdateCheckMetrics(SystemState *system_state,
224                               CheckResult result,
225                               CheckReaction reaction,
226                               DownloadErrorCode download_error_code);
227 
228 
229 // Helper function to report metrics after the completion of each
230 // update attempt. The following metrics are reported:
231 //
232 //  |kMetricAttemptNumber|
233 //  |kMetricAttemptPayloadType|
234 //  |kMetricAttemptPayloadSizeMiB|
235 //  |kMetricAttemptDurationSeconds|
236 //  |kMetricAttemptDurationUptimeSeconds|
237 //  |kMetricAttemptTimeSinceLastAttemptMinutes|
238 //  |kMetricAttemptTimeSinceLastAttemptUptimeMinutes|
239 //  |kMetricAttemptPayloadBytesDownloadedMiB|
240 //  |kMetricAttemptPayloadDownloadSpeedKBps|
241 //  |kMetricAttemptDownloadSource|
242 //  |kMetricAttemptResult|
243 //  |kMetricAttemptInternalErrorCode|
244 //  |kMetricAttemptDownloadErrorCode|
245 //
246 // The |kMetricAttemptInternalErrorCode| metric will only be reported
247 // if |internal_error_code| is not |kErrorSuccess|.
248 //
249 // The |kMetricAttemptDownloadErrorCode| metric will only be
250 // reported if |payload_download_error_code| is not |kUnset|.
251 //
252 // The values for the |kMetricAttemptTimeSinceLastAttemptMinutes| and
253 // |kMetricAttemptTimeSinceLastAttemptUptimeMinutes| metrics are
254 // automatically calculated and reported by maintaining persistent and
255 // process-local state variables.
256 void ReportUpdateAttemptMetrics(
257     SystemState *system_state,
258     int attempt_number,
259     PayloadType payload_type,
260     base::TimeDelta duration,
261     base::TimeDelta duration_uptime,
262     int64_t payload_size,
263     int64_t payload_bytes_downloaded,
264     int64_t payload_download_speed_bps,
265     DownloadSource download_source,
266     AttemptResult attempt_result,
267     ErrorCode internal_error_code,
268     DownloadErrorCode payload_download_error_code,
269     ConnectionType connection_type);
270 
271 // Reports the |kAbnormalTermination| for the |kMetricAttemptResult|
272 // metric. No other metrics in the UpdateEngine.Attempt.* namespace
273 // will be reported.
274 void ReportAbnormallyTerminatedUpdateAttemptMetrics(SystemState *system_state);
275 
276 // Helper function to report the after the completion of a successful
277 // update attempt. The following metrics are reported:
278 //
279 //  |kMetricSuccessfulUpdateAttemptCount|
280 //  |kMetricSuccessfulUpdateUpdatesAbandonedCount|
281 //  |kMetricSuccessfulUpdatePayloadType|
282 //  |kMetricSuccessfulUpdatePayloadSizeMiB|
283 //  |kMetricSuccessfulUpdateBytesDownloadedMiBHttpsServer|
284 //  |kMetricSuccessfulUpdateBytesDownloadedMiBHttpServer|
285 //  |kMetricSuccessfulUpdateBytesDownloadedMiBHttpPeer|
286 //  |kMetricSuccessfulUpdateBytesDownloadedMiB|
287 //  |kMetricSuccessfulUpdateDownloadSourcesUsed|
288 //  |kMetricSuccessfulUpdateDownloadOverheadPercentage|
289 //  |kMetricSuccessfulUpdateTotalDurationMinutes|
290 //  |kMetricSuccessfulUpdateRebootCount|
291 //  |kMetricSuccessfulUpdateUrlSwitchCount|
292 //
293 // The values for the |kMetricSuccessfulUpdateDownloadSourcesUsed| are
294 // |kMetricSuccessfulUpdateBytesDownloadedMiB| metrics automatically
295 // calculated from examining the |num_bytes_downloaded| array.
296 void ReportSuccessfulUpdateMetrics(
297     SystemState *system_state,
298     int attempt_count,
299     int updates_abandoned_count,
300     PayloadType payload_type,
301     int64_t payload_size,
302     int64_t num_bytes_downloaded[kNumDownloadSources],
303     int download_overhead_percentage,
304     base::TimeDelta total_duration,
305     int reboot_count,
306     int url_switch_count);
307 
308 // Helper function to report the after the completion of a SSL certificate
309 // check. One of the following metrics is reported:
310 //
311 //  |kMetricCertificateCheckUpdateCheck|
312 //  |kMetricCertificateCheckDownload|
313 void ReportCertificateCheckMetrics(SystemState* system_state,
314                                    ServerToCheck server_to_check,
315                                    CertificateCheckResult result);
316 
317 }  // namespace metrics
318 
319 }  // namespace chromeos_update_engine
320 
321 #endif  // UPDATE_ENGINE_METRICS_H_
322