blob: c55d4a503fb0bb6b6a430983966121eaf86658ac [file] [log] [blame]
// 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/1427219): 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.
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.
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_