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