components/metrics/metrics_log.h

   1 // Copyright 2014 The Chromium 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 // This file defines a set of user experience metrics data recorded by
   6 // the MetricsService.  This is the unit of data that is sent to the server.
   7
   8 #ifndef COMPONENTS_METRICS_METRICS_LOG_H_
   9 #define COMPONENTS_METRICS_METRICS_LOG_H_
  10
  11 #include <string>
  12 #include <vector>
  13
  14 #include "base/basictypes.h"
  15 #include "base/time/time.h"
  16 #include "components/metrics/proto/chrome_user_metrics_extension.pb.h"
  17
  18 class PrefRegistrySimple;
  19 class PrefService;
  20
  21 namespace base {
  22 class DictionaryValue;
  23 class HistogramSamples;
  24 }
  25
  26 namespace content {
  27 struct WebPluginInfo;
  28 }
  29
  30 namespace variations {
  31 struct ActiveGroupId;
  32 }
  33
  34 namespace metrics {
  35
  36 class MetricsProvider;
  37 class MetricsServiceClient;
  38
  39 class MetricsLog {
  40  public:
  41   enum LogType {
  42     INITIAL_STABILITY_LOG,  // The initial log containing stability stats.
  43     ONGOING_LOG,            // Subsequent logs in a session.
  44   };
  45
  46   // Creates a new metrics log of the specified type.
  47   // |client_id| is the identifier for this profile on this installation
  48   // |session_id| is an integer that's incremented on each application launch
  49   // |client| is used to interact with the embedder.
  50   // |local_state| is the PrefService that this instance should use.
  51   // Note: |this| instance does not take ownership of the |client|, but rather
  52   // stores a weak pointer to it. The caller should ensure that the |client| is
  53   // valid for the lifetime of this class.
  54   MetricsLog(const std::string& client_id,
  55              int session_id,
  56              LogType log_type,
  57              MetricsServiceClient* client,
  58              PrefService* local_state);
  59   virtual ~MetricsLog();
  60
  61   // Registers local state prefs used by this class.
  62   static void RegisterPrefs(PrefRegistrySimple* registry);
  63
  64   // Computes the MD5 hash of the given string, and returns the first 8 bytes of
  65   // the hash.
  66   static uint64 Hash(const std::string& value);
  67
  68   // Get the GMT buildtime for the current binary, expressed in seconds since
  69   // January 1, 1970 GMT.
  70   // The value is used to identify when a new build is run, so that previous
  71   // reliability stats, from other builds, can be abandoned.
  72   static int64 GetBuildTime();
  73
  74   // Convenience function to return the current time at a resolution in seconds.
  75   // This wraps base::TimeTicks, and hence provides an abstract time that is
  76   // always incrementing for use in measuring time durations.
  77   static int64 GetCurrentTime();
  78
  79   // Records a user-initiated action.
  80   void RecordUserAction(const std::string& key);
  81
  82   // Record any changes in a given histogram for transmission.
  83   void RecordHistogramDelta(const std::string& histogram_name,
  84                             const base::HistogramSamples& snapshot);
  85
  86   // Records the current operating environment, including metrics provided by
  87   // the specified set of |metrics_providers|.  Takes the list of installed
  88   // plugins, Google Update statistics, and synthetic trial IDs as parameters
  89   // because those can't be obtained synchronously from the UI thread.
  90   // A synthetic trial is one that is set up dynamically by code in Chrome. For
  91   // example, a pref may be mapped to a synthetic trial such that the group
  92   // is determined by the pref value.
  93   void RecordEnvironment(
  94       const std::vector<MetricsProvider*>& metrics_providers,
  95       const std::vector<variations::ActiveGroupId>& synthetic_trials,
  96       int64 install_date,
  97       int64 metrics_reporting_enabled_date);
  98
  99   // Loads the environment proto that was saved by the last RecordEnvironment()
 100   // call from prefs and clears the pref value. Returns true on success or false
 101   // if there was no saved environment in prefs or it could not be decoded.
 102   bool LoadSavedEnvironmentFromPrefs();
 103
 104   // Writes application stability metrics, including stability metrics provided
 105   // by the specified set of |metrics_providers|. The system profile portion of
 106   // the log must have already been filled in by a call to RecordEnvironment()
 107   // or LoadSavedEnvironmentFromPrefs().
 108   // NOTE: Has the side-effect of clearing the stability prefs..
 109   //
 110   // If this log is of type INITIAL_STABILITY_LOG, records additional info such
 111   // as number of incomplete shutdowns as well as extra breakpad and debugger
 112   // stats.
 113   void RecordStabilityMetrics(
 114       const std::vector<MetricsProvider*>& metrics_providers,
 115       base::TimeDelta incremental_uptime,
 116       base::TimeDelta uptime);
 117
 118   // Records general metrics based on the specified |metrics_providers|.
 119   void RecordGeneralMetrics(
 120       const std::vector<MetricsProvider*>& metrics_providers);
 121
 122   // Stop writing to this record and generate the encoded representation.
 123   // None of the Record* methods can be called after this is called.
 124   void CloseLog();
 125
 126   // Fills |encoded_log| with the serialized protobuf representation of the
 127   // record.  Must only be called after CloseLog() has been called.
 128   void GetEncodedLog(std::string* encoded_log);
 129
 130   const base::TimeTicks& creation_time() const {
 131     return creation_time_;
 132   }
 133
 134   int num_events() const {
 135     return uma_proto_.omnibox_event_size() +
 136            uma_proto_.user_action_event_size();
 137   }
 138
 139   LogType log_type() const { return log_type_; }
 140
 141  protected:
 142   // Exposed for the sake of mocking/accessing in test code.
 143
 144   // Fills |field_trial_ids| with the list of initialized field trials name and
 145   // group ids.
 146   virtual void GetFieldTrialIds(
 147       std::vector<variations::ActiveGroupId>* field_trial_ids) const;
 148
 149   ChromeUserMetricsExtension* uma_proto() { return &uma_proto_; }
 150
 151   // Exposed to allow subclass to access to export the uma_proto. Can be used
 152   // by external components to export logs to Chrome.
 153   const ChromeUserMetricsExtension* uma_proto() const {
 154     return &uma_proto_;
 155   }
 156
 157  private:
 158   // Returns true if the environment has already been filled in by a call to
 159   // RecordEnvironment() or LoadSavedEnvironmentFromPrefs().
 160   bool HasEnvironment() const;
 161
 162   // Returns true if the stability metrics have already been filled in by a
 163   // call to RecordStabilityMetrics().
 164   bool HasStabilityMetrics() const;
 165
 166   // Within the stability group, write required attributes.
 167   void WriteRequiredStabilityAttributes(PrefService* pref);
 168
 169   // Within the stability group, write attributes that need to be updated asap
 170   // and can't be delayed until the user decides to restart chromium.
 171   // Delaying these stats would bias metrics away from happy long lived
 172   // chromium processes (ones that don't crash, and keep on running).
 173   void WriteRealtimeStabilityAttributes(PrefService* pref,
 174                                         base::TimeDelta incremental_uptime,
 175                                         base::TimeDelta uptime);
 176
 177   // closed_ is true when record has been packed up for sending, and should
 178   // no longer be written to.  It is only used for sanity checking.
 179   bool closed_;
 180
 181   // The type of the log, i.e. initial or ongoing.
 182   const LogType log_type_;
 183
 184   // Stores the protocol buffer representation for this log.
 185   ChromeUserMetricsExtension uma_proto_;
 186
 187   // Used to interact with the embedder. Weak pointer; must outlive |this|
 188   // instance.
 189   MetricsServiceClient* const client_;
 190
 191   // The time when the current log was created.
 192   const base::TimeTicks creation_time_;
 193
 194   PrefService* local_state_;
 195
 196   DISALLOW_COPY_AND_ASSIGN(MetricsLog);
 197 };
 198
 199 }  // namespace metrics
 200
 201 #endif  // COMPONENTS_METRICS_METRICS_LOG_H_