1 // Copyright 2018 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_PERSISTENT_HISTOGRAMS_H_ 6 #define COMPONENTS_METRICS_PERSISTENT_HISTOGRAMS_H_ 7 8 #include <string> 9 10 #include "base/feature_list.h" 11 #include "base/files/file_path.h" 12 #include "base/metrics/field_trial_params.h" 13 #include "base/strings/string_piece.h" 14 15 // Feature definition for enabling histogram persistence. Note that this feature 16 // (along with its param `kPersistentHistogramsStorage`, declared below) is not 17 // used for Chrome on Linux, ChromeOS, Windows, macOS, and Android. Instead, 18 // histograms are persisted to a memory-mapped file, and set up before field 19 // trial initialization (see //chrome/app/chrome_main_delegate.cc). 20 BASE_DECLARE_FEATURE(kPersistentHistogramsFeature); 21 22 // If `kPersistentHistogramsStorage` is set to this, histograms will be 23 // allocated in a memory region backed by a file. 24 extern const char kPersistentHistogramStorageMappedFile[]; 25 26 // If `kPersistentHistogramsStorage` is set to this, histograms will be 27 // allocated on the heap, but using the same allocator as the one used for 28 // file-backed persistent histograms. 29 extern const char kPersistentHistogramStorageLocalMemory[]; 30 31 // Determines where histograms will be allocated (should either be 32 // `kPersistentHistogramStorageMappedFile` or 33 // `kPersistentHistogramStorageLocalMemory`). 34 extern const base::FeatureParam<std::string> kPersistentHistogramsStorage; 35 36 // Persistent browser metrics need to be persisted somewhere. This constant 37 // provides a known string to be used for both the allocator's internal name and 38 // for a file on disk (relative to metrics_dir) to which they can be saved. This 39 // is exported so the name can also be used as a "pref" during configuration. 40 extern const char kBrowserMetricsName[]; 41 42 // Like above, this provides a known string to be used for persistent browser 43 // metrics. However, metrics under this are "deferred" and sent along with a 44 // future session's metrics instead of independently. 45 extern const char kDeferredBrowserMetricsName[]; 46 47 // Do all the checking and work necessary to enable persistent histograms. 48 // `metrics_dir` specifies the root directory where persistent histograms will 49 // live. If `persistent_histograms_enabled` is false, this is essentially a 50 // no-op (histograms will continue being allocated on the heap). Otherwise, 51 // `storage`, which should be either `kPersistentHistogramStorageMappedFile` or 52 // `kPersistentHistogramStorageLocalMemory`, determines where histograms will be 53 // allocated. 54 // Note: After a call to this, a call toPersistentHistogramsCleanup() below 55 // should be made when appropriate. 56 void InstantiatePersistentHistograms(const base::FilePath& metrics_dir, 57 bool persistent_histograms_enabled, 58 base::StringPiece storage); 59 60 // Schedule the tasks required to cleanup the persistent metrics files. 61 void PersistentHistogramsCleanup(const base::FilePath& metrics_dir); 62 63 // Calls InstantiatePersistentHistograms() using `kPersistentHistogramsFeature` 64 // and `kPersistentHistogramsStorage` as params. PersistentHistogramsCleanup() 65 // is also called immediately after. 66 void InstantiatePersistentHistogramsWithFeaturesAndCleanup( 67 const base::FilePath& metrics_dir); 68 69 // After calling this, histograms from this session that were not sent (i.e., 70 // unlogged samples) will be sent along with a future session's metrics. 71 // Normally, those unlogged samples are sent as an "independent log", which uses 72 // the system profile in the persistent file. However, there are scenarios where 73 // the browser must exit before a system profile is written to the file, which 74 // results in the metrics from that session being lost. Calling this function 75 // will make so that the unlogged samples are sent with a future session's 76 // metrics (whichever is the first to read the file). Note that this may come at 77 // the cost of associating the metrics with an incorrect system profile. Returns 78 // whether the operation was successful. 79 // Note: If you plan on using this, please make sure to get a review from the 80 // metrics team. Using this may lead to reporting additional histograms that 81 // may not be relevant to what is being experimented with, which can cause 82 // confusing/disruptive data. 83 bool DeferBrowserMetrics(const base::FilePath& metrics_dir); 84 85 #endif // COMPONENTS_METRICS_PERSISTENT_HISTOGRAMS_H_ 86