1 // Copyright 2017 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 BASE_METRICS_SINGLE_SAMPLE_METRICS_H_ 6 #define BASE_METRICS_SINGLE_SAMPLE_METRICS_H_ 7 8 #include <memory> 9 #include <string> 10 11 #include "base/base_export.h" 12 #include "base/memory/raw_ptr.h" 13 #include "base/metrics/histogram_base.h" 14 15 namespace base { 16 17 // See base/metrics/histograms.h for parameter definitions. Must only be used 18 // and destroyed from the same thread as construction. 19 class BASE_EXPORT SingleSampleMetric { 20 public: 21 virtual ~SingleSampleMetric() = default; 22 23 virtual void SetSample(HistogramBase::Sample sample) = 0; 24 }; 25 26 // Factory for creating single sample metrics. A single sample metric only 27 // reports its sample once at destruction time. The sample may be changed prior 28 // to destruction using the SetSample() method as many times as desired. 29 // 30 // The metric creation methods are safe to call from any thread, however the 31 // returned class must only be used and destroyed from the same thread as 32 // construction. 33 // 34 // See base/metrics/histogram_macros.h for usage recommendations and 35 // base/metrics/histogram.h for full parameter definitions. 36 class BASE_EXPORT SingleSampleMetricsFactory { 37 public: 38 virtual ~SingleSampleMetricsFactory() = default; 39 40 // Returns the factory provided by SetFactory(), or if no factory has been set 41 // a default factory will be provided (future calls to SetFactory() will fail 42 // if the default factory is ever vended). 43 static SingleSampleMetricsFactory* Get(); 44 static void SetFactory(std::unique_ptr<SingleSampleMetricsFactory> factory); 45 46 // The factory normally persists until process shutdown, but in testing we 47 // should avoid leaking it since it sets a global. 48 static void DeleteFactoryForTesting(); 49 50 // The methods below return a single sample metric for counts histograms; see 51 // method comments for the corresponding histogram macro. 52 53 // UMA_HISTOGRAM_CUSTOM_COUNTS() 54 virtual std::unique_ptr<SingleSampleMetric> CreateCustomCountsMetric( 55 const std::string& histogram_name, 56 HistogramBase::Sample min, 57 HistogramBase::Sample max, 58 uint32_t bucket_count) = 0; 59 }; 60 61 // Default implementation for when no factory has been provided to the process. 62 // Samples are only recorded within the current process in this case, so samples 63 // will be lost in the event of sudden process termination. 64 class BASE_EXPORT DefaultSingleSampleMetricsFactory 65 : public SingleSampleMetricsFactory { 66 public: 67 DefaultSingleSampleMetricsFactory() = default; 68 DefaultSingleSampleMetricsFactory(const DefaultSingleSampleMetricsFactory&) = 69 delete; 70 DefaultSingleSampleMetricsFactory& operator=( 71 const DefaultSingleSampleMetricsFactory&) = delete; 72 ~DefaultSingleSampleMetricsFactory() override = default; 73 74 // SingleSampleMetricsFactory: 75 std::unique_ptr<SingleSampleMetric> CreateCustomCountsMetric( 76 const std::string& histogram_name, 77 HistogramBase::Sample min, 78 HistogramBase::Sample max, 79 uint32_t bucket_count) override; 80 }; 81 82 class BASE_EXPORT DefaultSingleSampleMetric : public SingleSampleMetric { 83 public: 84 DefaultSingleSampleMetric(const std::string& histogram_name, 85 HistogramBase::Sample min, 86 HistogramBase::Sample max, 87 uint32_t bucket_count, 88 int32_t flags); 89 90 DefaultSingleSampleMetric(const DefaultSingleSampleMetric&) = delete; 91 DefaultSingleSampleMetric& operator=(const DefaultSingleSampleMetric&) = 92 delete; 93 94 ~DefaultSingleSampleMetric() override; 95 96 // SingleSampleMetric: 97 void SetSample(HistogramBase::Sample sample) override; 98 99 private: 100 const raw_ptr<HistogramBase> histogram_; 101 102 // The last sample provided to SetSample(). We use -1 as a sentinel value to 103 // indicate no sample has been set. 104 HistogramBase::Sample sample_ = -1; 105 }; 106 107 } // namespace base 108 109 #endif // BASE_METRICS_SINGLE_SAMPLE_METRICS_H_ 110