Home | History | Annotate | Download | only in update_engine 
      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