components/metrics/metrics_provider.h

   1 // Copyright 2014 The Chromium Authors
   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 COMPONENTS_METRICS_METRICS_PROVIDER_H_
   6 #define COMPONENTS_METRICS_METRICS_PROVIDER_H_
   7
   8 #include "base/functional/callback.h"
   9 #include "base/time/time.h"
  10
  11 namespace base {
  12 class HistogramSnapshotManager;
  13 }  // namespace base
  14
  15 namespace metrics {
  16
  17 class ChromeUserMetricsExtension;
  18 class SystemProfileProto;
  19
  20 // MetricsProvider is an interface allowing different parts of the UMA protos to
  21 // be filled out by different classes.
  22 class MetricsProvider {
  23  public:
  24   MetricsProvider();
  25
  26   MetricsProvider(const MetricsProvider&) = delete;
  27   MetricsProvider& operator=(const MetricsProvider&) = delete;
  28
  29   virtual ~MetricsProvider();
  30
  31   // Called after initialization of MetricsService and field trials.
  32   virtual void Init();
  33
  34   // Called during service initialization to allow the provider to start any
  35   // async initialization tasks.  The service will wait for the provider to
  36   // call |done_callback| before generating logs for the current session.
  37   // |done_callback| must be run on the same thread that calls |AsyncInit|.
  38   virtual void AsyncInit(base::OnceClosure done_callback);
  39
  40   // Called by OnDidCreateMetricsLog() to provide histograms. If histograms
  41   // are not emitted successfully, it will be called in
  42   // ProvideCurrentSessionData().
  43   // Returns whether or not histograms are emitted successfully.
  44   // Only override this function if:
  45   // 1. You want your histograms to be included in every record uploaded to the
  46   // server.
  47   // 2. You will not override ProvideCurrentSessionData(),
  48   // OnDidCreateMetricsLog(), or ProvideStabilityMetrics().
  49   // TODO(crbug/1427219): Refactor the code to remove requirement 2.
  50   virtual bool ProvideHistograms();
  51
  52   // Called when a new MetricsLog is created.
  53   virtual void OnDidCreateMetricsLog();
  54
  55   // Called when metrics recording has been enabled.
  56   virtual void OnRecordingEnabled();
  57
  58   // Called when metrics recording has been disabled.
  59   virtual void OnRecordingDisabled();
  60
  61   // Called when metrics client identifiers have been reset.
  62   //
  63   // Metrics providers should clean up any persisted state that could be used to
  64   // associate the previous identifier with the new one.
  65   //
  66   // Currently this method is only invoked in UKM.
  67   virtual void OnClientStateCleared();
  68
  69   // Called when the application is going into background mode, on platforms
  70   // where applications may be killed when going into the background (Android,
  71   // iOS). Providers that buffer histogram data in memory should persist
  72   // histograms in this callback, as the application may be killed without
  73   // further notification after this callback.
  74   virtual void OnAppEnterBackground();
  75
  76   // Returns whether there are "independent" metrics that can be retrieved
  77   // with a call to ProvideIndependentMetrics().
  78   virtual bool HasIndependentMetrics();
  79
  80   // Provides a complete and independent uma proto + metrics for uploading.
  81   // Called once every time HasIndependentMetrics() returns true. The passed in
  82   // |uma_proto| is by default filled with current session id and core system
  83   // profile information. This function is called on main thread, but the
  84   // provider can do async work to fill in |uma_proto| and run |done_callback|
  85   // on calling thread when complete. Calling |serialize_log_callback| will
  86   // serialize |uma_proto| so that it is primed to be sent. As an optimization,
  87   // the provider should call this on a background thread before posting back
  88   // |done_callback| on the calling thread. However, it is fine not to call this
  89   // if the thread hopping could introduce data loss (e.g., since the user may
  90   // shut down the browser before |done_callback| is called). In this case,
  91   // |done_callback| will "manually" call it synchronously. Ownership of the
  92   // passed objects remains with the caller and those objects will live until
  93   // the callback is executed.
  94   virtual void ProvideIndependentMetrics(
  95       base::OnceClosure serialize_log_callback,
  96       base::OnceCallback<void(bool)> done_callback,
  97       ChromeUserMetricsExtension* uma_proto,
  98       base::HistogramSnapshotManager* snapshot_manager);
  99
 100   // Provides additional metrics into the system profile. This is a convenience
 101   // method over ProvideSystemProfileMetricsWithLogCreationTime() without the
 102   // |log_creation_time| param. Should not be called directly by services.
 103   virtual void ProvideSystemProfileMetrics(
 104       SystemProfileProto* system_profile_proto);
 105
 106   // Provides additional metrics into the system profile. The log creation
 107   // time param provides a timestamp of when the log was opened, which is needed
 108   // for some metrics providers.
 109   virtual void ProvideSystemProfileMetricsWithLogCreationTime(
 110       base::TimeTicks log_creation_time,
 111       SystemProfileProto* system_profile_proto);
 112
 113   // Called once at startup to see whether this provider has critical data
 114   // to provide about the previous session.
 115   // Returning true will trigger ProvidePreviousSessionData on all other
 116   // registered metrics providers.
 117   // Default implementation always returns false.
 118   virtual bool HasPreviousSessionData();
 119
 120   // Called when building a log about the previous session, so the provider
 121   // can provide data about it.  Stability metrics can be provided
 122   // directly into |stability_proto| fields or by logging stability histograms
 123   // via the UMA_STABILITY_HISTOGRAM_ENUMERATION() macro.
 124   virtual void ProvidePreviousSessionData(
 125       ChromeUserMetricsExtension* uma_proto);
 126
 127   // Called when building a log about the current session, so the provider
 128   // can provide data about it.
 129   virtual void ProvideCurrentSessionData(ChromeUserMetricsExtension* uma_proto);
 130
 131   // Called when building a UKM log about the current session. UKM-specific data
 132   // should generally only be emitted through this method, and UMA data should
 133   // be emitted through ProvideCurrentSessionData().
 134   virtual void ProvideCurrentSessionUKMData();
 135
 136   // Provides additional stability metrics. Stability metrics can be provided
 137   // directly into |stability_proto| fields or by logging stability histograms
 138   // via the UMA_STABILITY_HISTOGRAM_ENUMERATION() macro.
 139   virtual void ProvideStabilityMetrics(
 140       SystemProfileProto* system_profile_proto);
 141
 142   // Called to indicate that saved stability prefs should be cleared, e.g.
 143   // because they are from an old version and should not be kept.
 144   virtual void ClearSavedStabilityMetrics();
 145
 146   // Called during regular collection to explicitly load histogram snapshots
 147   // using a snapshot manager. Calls to only PrepareDelta(), not PrepareDeltas()
 148   // (plural), should be made.
 149   virtual void RecordHistogramSnapshots(
 150       base::HistogramSnapshotManager* snapshot_manager);
 151
 152   // Called during collection of initial metrics to explicitly load histogram
 153   // snapshots using a snapshot manager. Calls to only PrepareDelta(), not
 154   // PrepareDeltas() (plural), should be made.
 155   virtual void RecordInitialHistogramSnapshots(
 156       base::HistogramSnapshotManager* snapshot_manager);
 157
 158  protected:
 159   // Used to indicate whether ProvideHistograms() successfully emits histograms
 160   // when called in OnDidCreateMetricsLog().
 161   bool emitted_ = false;
 162 };
 163
 164 }  // namespace metrics
 165
 166 #endif  // COMPONENTS_METRICS_METRICS_PROVIDER_H_