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