1 //
2 // Copyright (C) 2017 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_REPORTER_INTERFACE_H_
18 #define UPDATE_ENGINE_METRICS_REPORTER_INTERFACE_H_
19 
20 #include <memory>
21 #include <string>
22 
23 #include <base/time/time.h>
24 
25 #include "update_engine/common/constants.h"
26 #include "update_engine/common/error_code.h"
27 #include "update_engine/metrics_constants.h"
28 #include "update_engine/system_state.h"
29 
30 namespace chromeos_update_engine {
31 
32 enum class ServerToCheck;
33 enum class CertificateCheckResult;
34 
35 namespace metrics {
36 
37 std::unique_ptr<MetricsReporterInterface> CreateMetricsReporter();
38 
39 }  // namespace metrics
40 
41 class MetricsReporterInterface {
42  public:
43   virtual ~MetricsReporterInterface() = default;
44 
45   virtual void Initialize() = 0;
46 
47   // Helper function to report metrics related to user-initiated rollback. The
48   // following metrics are reported:
49   //
50   //  |kMetricRollbackResult|
51   virtual void ReportRollbackMetrics(metrics::RollbackResult result) = 0;
52 
53   // Helper function to report metrics related to enterprise (admin-initiated)
54   // rollback:
55   //
56   //  |kMetricEnterpriseRollbackSuccess|
57   //  |kMetricEnterpriseRollbackFailure|
58   virtual void ReportEnterpriseRollbackMetrics(
59       bool success, const std::string& rollback_version) = 0;
60 
61   // Helper function to report metrics reported once a day. The
62   // following metrics are reported:
63   //
64   //  |kMetricDailyOSAgeDays|
65   virtual void ReportDailyMetrics(base::TimeDelta os_age) = 0;
66 
67   // Helper function to report metrics after completing an update check
68   // with the ChromeOS update server ("Omaha"). The following metrics
69   // are reported:
70   //
71   //  |kMetricCheckResult|
72   //  |kMetricCheckReaction|
73   //  |kMetricCheckDownloadErrorCode|
74   //  |kMetricCheckTimeSinceLastCheckMinutes|
75   //  |kMetricCheckTimeSinceLastCheckUptimeMinutes|
76   //  |kMetricCheckTargetVersion|
77   //  |kMetricCheckRollbackTargetVersion|
78   //
79   // The |kMetricCheckResult| metric will only be reported if |result|
80   // is not |kUnset|.
81   //
82   // The |kMetricCheckReaction| metric will only be reported if
83   // |reaction| is not |kUnset|.
84   //
85   // The |kMetricCheckDownloadErrorCode| will only be reported if
86   // |download_error_code| is not |kUnset|.
87   //
88   // The values for the |kMetricCheckTimeSinceLastCheckMinutes| and
89   // |kMetricCheckTimeSinceLastCheckUptimeMinutes| metrics are
90   // automatically reported and calculated by maintaining persistent
91   // and process-local state variables.
92   //
93   // |kMetricCheckTargetVersion| reports the first section of the target version
94   // if it's set, |kMetricCheckRollbackTargetVersion| reports the same, but only
95   // if rollback is also allowed using enterprise policy.
96   virtual void ReportUpdateCheckMetrics(
97       SystemState* system_state,
98       metrics::CheckResult result,
99       metrics::CheckReaction reaction,
100       metrics::DownloadErrorCode download_error_code) = 0;
101 
102   // Helper function to report metrics after the completion of each
103   // update attempt. The following metrics are reported:
104   //
105   //  |kMetricAttemptNumber|
106   //  |kMetricAttemptPayloadType|
107   //  |kMetricAttemptPayloadSizeMiB|
108   //  |kMetricAttemptDurationMinutes|
109   //  |kMetricAttemptDurationUptimeMinutes|
110   //  |kMetricAttemptTimeSinceLastAttemptMinutes|
111   //  |kMetricAttemptTimeSinceLastAttemptUptimeMinutes|
112   //  |kMetricAttemptResult|
113   //  |kMetricAttemptInternalErrorCode|
114   //
115   // The |kMetricAttemptInternalErrorCode| metric will only be reported
116   // if |internal_error_code| is not |kErrorSuccess|.
117   //
118   // The |kMetricAttemptDownloadErrorCode| metric will only be
119   // reported if |payload_download_error_code| is not |kUnset|.
120   //
121   // The values for the |kMetricAttemptTimeSinceLastAttemptMinutes| and
122   // |kMetricAttemptTimeSinceLastAttemptUptimeMinutes| metrics are
123   // automatically calculated and reported by maintaining persistent and
124   // process-local state variables.
125   virtual void ReportUpdateAttemptMetrics(SystemState* system_state,
126                                           int attempt_number,
127                                           PayloadType payload_type,
128                                           base::TimeDelta duration,
129                                           base::TimeDelta duration_uptime,
130                                           int64_t payload_size,
131                                           metrics::AttemptResult attempt_result,
132                                           ErrorCode internal_error_code) = 0;
133 
134   // Helper function to report download metrics after the completion of each
135   // update attempt. The following metrics are reported:
136   //
137   // |kMetricAttemptPayloadBytesDownloadedMiB|
138   // |kMetricAttemptPayloadDownloadSpeedKBps|
139   // |kMetricAttemptDownloadSource|
140   // |kMetricAttemptDownloadErrorCode|
141   // |kMetricAttemptConnectionType|
142   virtual void ReportUpdateAttemptDownloadMetrics(
143       int64_t payload_bytes_downloaded,
144       int64_t payload_download_speed_bps,
145       DownloadSource download_source,
146       metrics::DownloadErrorCode payload_download_error_code,
147       metrics::ConnectionType connection_type) = 0;
148 
149   // Reports the |kAbnormalTermination| for the |kMetricAttemptResult|
150   // metric. No other metrics in the UpdateEngine.Attempt.* namespace
151   // will be reported.
152   virtual void ReportAbnormallyTerminatedUpdateAttemptMetrics() = 0;
153 
154   // Helper function to report the after the completion of a successful
155   // update attempt. The following metrics are reported:
156   //
157   //  |kMetricSuccessfulUpdateAttemptCount|
158   //  |kMetricSuccessfulUpdateUpdatesAbandonedCount|
159   //  |kMetricSuccessfulUpdatePayloadType|
160   //  |kMetricSuccessfulUpdatePayloadSizeMiB|
161   //  |kMetricSuccessfulUpdateBytesDownloadedMiBHttpsServer|
162   //  |kMetricSuccessfulUpdateBytesDownloadedMiBHttpServer|
163   //  |kMetricSuccessfulUpdateBytesDownloadedMiBHttpPeer|
164   //  |kMetricSuccessfulUpdateBytesDownloadedMiB|
165   //  |kMetricSuccessfulUpdateDownloadSourcesUsed|
166   //  |kMetricSuccessfulUpdateDownloadOverheadPercentage|
167   //  |kMetricSuccessfulUpdateTotalDurationMinutes|
168   //  |kMetricSuccessfulUpdateTotalDurationUptimeMinutes|
169   //  |kMetricSuccessfulUpdateRebootCount|
170   //  |kMetricSuccessfulUpdateUrlSwitchCount|
171   //
172   // The values for the |kMetricSuccessfulUpdateDownloadSourcesUsed| are
173   // |kMetricSuccessfulUpdateBytesDownloadedMiB| metrics automatically
174   // calculated from examining the |num_bytes_downloaded| array.
175   virtual void ReportSuccessfulUpdateMetrics(
176       int attempt_count,
177       int updates_abandoned_count,
178       PayloadType payload_type,
179       int64_t payload_size,
180       int64_t num_bytes_downloaded[kNumDownloadSources],
181       int download_overhead_percentage,
182       base::TimeDelta total_duration,
183       base::TimeDelta total_duration_uptime,
184       int reboot_count,
185       int url_switch_count) = 0;
186 
187   // Helper function to report the after the completion of a SSL certificate
188   // check. One of the following metrics is reported:
189   //
190   //  |kMetricCertificateCheckUpdateCheck|
191   //  |kMetricCertificateCheckDownload|
192   virtual void ReportCertificateCheckMetrics(ServerToCheck server_to_check,
193                                              CertificateCheckResult result) = 0;
194 
195   // Helper function to report the number failed update attempts. The following
196   // metrics are reported:
197   //
198   // |kMetricFailedUpdateCount|
199   virtual void ReportFailedUpdateCount(int target_attempt) = 0;
200 
201   // Helper function to report the time interval in minutes between a
202   // successful update and the reboot into the updated system. The following
203   // metrics are reported:
204   //
205   // |kMetricTimeToRebootMinutes|
206   virtual void ReportTimeToReboot(int time_to_reboot_minutes) = 0;
207 
208   // Helper function to report the source of installation data. The following
209   // metrics are reported:
210   //
211   // |kMetricInstallDateProvisioningSource|
212   virtual void ReportInstallDateProvisioningSource(int source, int max) = 0;
213 
214   // Helper function to report an internal error code. The following metrics are
215   // reported:
216   //
217   // |kMetricAttemptInternalErrorCode|
218   virtual void ReportInternalErrorCode(ErrorCode error_code) = 0;
219 
220   // Helper function to report metrics related to the verified boot key
221   // versions:
222   //
223   //  |kMetricKernelMinVersion|
224   //  |kMetricKernelMaxRollforwardVersion|
225   //  |kMetricKernelMaxRollforwardSetSuccess|
226   virtual void ReportKeyVersionMetrics(int kernel_min_version,
227                                        int kernel_max_rollforward_version,
228                                        bool kernel_max_rollforward_success) = 0;
229 
230   // Helper function to report the duration between an update being seen by the
231   // client to the update being applied. Updates are not always immediately
232   // applied when seen, several enterprise policies can affect when an update
233   // would actually be downloaded and applied.
234   //
235   // This metric should only be reported for enterprise enrolled devices.
236   //
237   // The following metrics are reported from this function:
238   //   If |has_time_restriction_policy| is false:
239   //     |kMetricSuccessfulUpdateDurationFromSeenDays|
240   //   If |has_time_restriction_policy| is true:
241   //     |kMetricSuccessfulUpdateDurationFromSeenTimeRestrictedDays|
242   //
243   virtual void ReportEnterpriseUpdateSeenToDownloadDays(
244       bool has_time_restriction_policy, int time_to_update_days) = 0;
245 };
246 
247 }  // namespace chromeos_update_engine
248 
249 #endif  // UPDATE_ENGINE_METRICS_REPORTER_INTERFACE_H_
250