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. Ownership of the passed objects remains 86 // with the caller and those objects will live until the callback is executed. 87 virtual void ProvideIndependentMetrics( 88 base::OnceCallback<void(bool)> done_callback, 89 ChromeUserMetricsExtension* uma_proto, 90 base::HistogramSnapshotManager* snapshot_manager); 91 92 // Provides additional metrics into the system profile. This is a convenience 93 // method over ProvideSystemProfileMetricsWithLogCreationTime() without the 94 // |log_creation_time| param. Should not be called directly by services. 95 virtual void ProvideSystemProfileMetrics( 96 SystemProfileProto* system_profile_proto); 97 98 // Provides additional metrics into the system profile. The log creation 99 // time param provides a timestamp of when the log was opened, which is needed 100 // for some metrics providers. 101 virtual void ProvideSystemProfileMetricsWithLogCreationTime( 102 base::TimeTicks log_creation_time, 103 SystemProfileProto* system_profile_proto); 104 105 // Called once at startup to see whether this provider has critical data 106 // to provide about the previous session. 107 // Returning true will trigger ProvidePreviousSessionData on all other 108 // registered metrics providers. 109 // Default implementation always returns false. 110 virtual bool HasPreviousSessionData(); 111 112 // Called when building a log about the previous session, so the provider 113 // can provide data about it. Stability metrics can be provided 114 // directly into |stability_proto| fields or by logging stability histograms 115 // via the UMA_STABILITY_HISTOGRAM_ENUMERATION() macro. 116 virtual void ProvidePreviousSessionData( 117 ChromeUserMetricsExtension* uma_proto); 118 119 // Called when building a log about the current session, so the provider 120 // can provide data about it. 121 virtual void ProvideCurrentSessionData(ChromeUserMetricsExtension* uma_proto); 122 123 // Called when building a UKM log about the current session. UKM-specific data 124 // should generally only be emitted through this method, and UMA data should 125 // be emitted through ProvideCurrentSessionData(). 126 virtual void ProvideCurrentSessionUKMData(); 127 128 // Provides additional stability metrics. 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 ProvideStabilityMetrics( 132 SystemProfileProto* system_profile_proto); 133 134 // Called to indicate that saved stability prefs should be cleared, e.g. 135 // because they are from an old version and should not be kept. 136 virtual void ClearSavedStabilityMetrics(); 137 138 // Called during regular collection to explicitly load histogram snapshots 139 // using a snapshot manager. Calls to only PrepareDelta(), not PrepareDeltas() 140 // (plural), should be made. 141 virtual void RecordHistogramSnapshots( 142 base::HistogramSnapshotManager* snapshot_manager); 143 144 // Called during collection of initial metrics to explicitly load histogram 145 // snapshots using a snapshot manager. Calls to only PrepareDelta(), not 146 // PrepareDeltas() (plural), should be made. 147 virtual void RecordInitialHistogramSnapshots( 148 base::HistogramSnapshotManager* snapshot_manager); 149 150 protected: 151 // Used to indicate whether ProvideHistograms() successfully emits histograms 152 // when called in OnDidCreateMetricsLog(). 153 bool emitted_ = false; 154 }; 155 156 } // namespace metrics 157 158 #endif // COMPONENTS_METRICS_METRICS_PROVIDER_H_ 159