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