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.com/40899764): 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 // Called when a document first starts loading. 77 virtual void OnPageLoadStarted(); 78 79 // Returns whether there are "independent" metrics that can be retrieved 80 // with a call to ProvideIndependentMetrics(). 81 virtual bool HasIndependentMetrics(); 82 83 // Provides a complete and independent uma proto + metrics for uploading. 84 // Called once every time HasIndependentMetrics() returns true. The passed in 85 // |uma_proto| is by default filled with current session id and core system 86 // profile information. This function is called on main thread, but the 87 // provider can do async work to fill in |uma_proto| and run |done_callback| 88 // on calling thread when complete. Calling |serialize_log_callback| will 89 // serialize |uma_proto| so that it is primed to be sent. As an optimization, 90 // the provider should call this on a background thread before posting back 91 // |done_callback| on the calling thread. However, it is fine not to call this 92 // if the thread hopping could introduce data loss (e.g., since the user may 93 // shut down the browser before |done_callback| is called). In this case, 94 // |done_callback| will "manually" call it synchronously. Ownership of the 95 // passed objects remains with the caller and those objects will live until 96 // the callback is executed. 97 virtual void ProvideIndependentMetrics( 98 base::OnceClosure serialize_log_callback, 99 base::OnceCallback<void(bool)> done_callback, 100 ChromeUserMetricsExtension* uma_proto, 101 base::HistogramSnapshotManager* snapshot_manager); 102 103 // Provides additional metrics into the system profile. This is a convenience 104 // method over ProvideSystemProfileMetricsWithLogCreationTime() without the 105 // |log_creation_time| param. Should not be called directly by services. 106 // Do not log histograms within this function; they will not necessarily be 107 // added to the UMA record that this system profile is part of. 108 virtual void ProvideSystemProfileMetrics( 109 SystemProfileProto* system_profile_proto); 110 111 // Provides additional metrics into the system profile. The log creation 112 // time param provides a timestamp of when the log was opened, which is needed 113 // for some metrics providers. 114 // Do not log histograms within this function; they will not necessarily be 115 // added to the UMA record that this system profile is part of. 116 virtual void ProvideSystemProfileMetricsWithLogCreationTime( 117 base::TimeTicks log_creation_time, 118 SystemProfileProto* system_profile_proto); 119 120 // Called once at startup to see whether this provider has critical data 121 // to provide about the previous session. 122 // Returning true will trigger ProvidePreviousSessionData on all other 123 // registered metrics providers. 124 // Default implementation always returns false. 125 virtual bool HasPreviousSessionData(); 126 127 // Called when building a log about the previous session, so the provider 128 // can provide data about it. Stability metrics can be provided 129 // directly into |stability_proto| fields or by logging stability histograms 130 // via the UMA_STABILITY_HISTOGRAM_ENUMERATION() macro. 131 virtual void ProvidePreviousSessionData( 132 ChromeUserMetricsExtension* uma_proto); 133 134 // Called when building a log about the current session, so the provider 135 // can provide data about it. 136 virtual void ProvideCurrentSessionData(ChromeUserMetricsExtension* uma_proto); 137 138 // Called when building a UKM log about the current session. UKM-specific data 139 // should generally only be emitted through this method, and UMA data should 140 // be emitted through ProvideCurrentSessionData(). 141 virtual void ProvideCurrentSessionUKMData(); 142 143 // Provides additional stability metrics. Stability metrics can be provided 144 // directly into |stability_proto| fields or by logging stability histograms 145 // via the UMA_STABILITY_HISTOGRAM_ENUMERATION() macro. 146 virtual void ProvideStabilityMetrics( 147 SystemProfileProto* system_profile_proto); 148 149 // Called to indicate that saved stability prefs should be cleared, e.g. 150 // because they are from an old version and should not be kept. 151 virtual void ClearSavedStabilityMetrics(); 152 153 // Called during regular collection to explicitly load histogram snapshots 154 // using a snapshot manager. Calls to only PrepareDelta(), not PrepareDeltas() 155 // (plural), should be made. 156 virtual void RecordHistogramSnapshots( 157 base::HistogramSnapshotManager* snapshot_manager); 158 159 // Called during collection of initial metrics to explicitly load histogram 160 // snapshots using a snapshot manager. Calls to only PrepareDelta(), not 161 // PrepareDeltas() (plural), should be made. 162 virtual void RecordInitialHistogramSnapshots( 163 base::HistogramSnapshotManager* snapshot_manager); 164 165 protected: 166 // Used to indicate whether ProvideHistograms() successfully emits histograms 167 // when called in OnDidCreateMetricsLog(). 168 bool emitted_ = false; 169 }; 170 171 } // namespace metrics 172 173 #endif // COMPONENTS_METRICS_METRICS_PROVIDER_H_ 174