1 // Copyright 2014 The Chromium Authors. All rights reserved. 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_HISTOGRAM_MACROS_H_ 6 #define BASE_METRICS_HISTOGRAM_MACROS_H_ 7 8 #include "base/atomicops.h" 9 #include "base/logging.h" 10 #include "base/metrics/histogram.h" 11 #include "base/time/time.h" 12 13 // Macros for efficient use of histograms. See documentation in histogram.h. 14 // 15 // UMA_HISTOGRAM_SPARSE_SLOWLY is defined in sparse_histogram.h as it has 16 // different #include dependencies. 17 18 //------------------------------------------------------------------------------ 19 // Histograms are often put in areas where they are called many many times, and 20 // performance is critical. As a result, they are designed to have a very low 21 // recurring cost of executing (adding additional samples). Toward that end, 22 // the macros declare a static pointer to the histogram in question, and only 23 // take a "slow path" to construct (or find) the histogram on the first run 24 // through the macro. We leak the histograms at shutdown time so that we don't 25 // have to validate using the pointers at any time during the running of the 26 // process. 27 28 // The following code is generally what a thread-safe static pointer 29 // initialization looks like for a histogram (after a macro is expanded). This 30 // sample is an expansion (with comments) of the code for 31 // LOCAL_HISTOGRAM_CUSTOM_COUNTS(). 32 33 /* 34 do { 35 // The pointer's presence indicates the initialization is complete. 36 // Initialization is idempotent, so it can safely be atomically repeated. 37 static base::subtle::AtomicWord atomic_histogram_pointer = 0; 38 39 // Acquire_Load() ensures that we acquire visibility to the pointed-to data 40 // in the histogram. 41 base::Histogram* histogram_pointer(reinterpret_cast<base::Histogram*>( 42 base::subtle::Acquire_Load(&atomic_histogram_pointer))); 43 44 if (!histogram_pointer) { 45 // This is the slow path, which will construct OR find the matching 46 // histogram. FactoryGet includes locks on a global histogram name map 47 // and is completely thread safe. 48 histogram_pointer = base::Histogram::FactoryGet( 49 name, min, max, bucket_count, base::HistogramBase::kNoFlags); 50 51 // Use Release_Store to ensure that the histogram data is made available 52 // globally before we make the pointer visible. 53 // Several threads may perform this store, but the same value will be 54 // stored in all cases (for a given named/spec'ed histogram). 55 // We could do this without any barrier, since FactoryGet entered and 56 // exited a lock after construction, but this barrier makes things clear. 57 base::subtle::Release_Store(&atomic_histogram_pointer, 58 reinterpret_cast<base::subtle::AtomicWord>(histogram_pointer)); 59 } 60 61 // Ensure calling contract is upheld, and the name does NOT vary. 62 DCHECK(histogram_pointer->histogram_name() == constant_histogram_name); 63 64 histogram_pointer->Add(sample); 65 } while (0); 66 */ 67 68 // The above pattern is repeated in several macros. The only elements that 69 // vary are the invocation of the Add(sample) vs AddTime(sample), and the choice 70 // of which FactoryGet method to use. The different FactoryGet methods have 71 // various argument lists, so the function with its argument list is provided as 72 // a macro argument here. The name is only used in a DCHECK, to assure that 73 // callers don't try to vary the name of the histogram (which would tend to be 74 // ignored by the one-time initialization of the histogtram_pointer). 75 76 // In some cases (integration into 3rd party code), it's useful to seperate the 77 // definition of |atomic_histogram_poiner| from its use. To achieve this we 78 // define HISTOGRAM_POINTER_USE, which uses an |atomic_histogram_pointer|, and 79 // STATIC_HISTOGRAM_POINTER_BLOCK, which defines an |atomic_histogram_pointer| 80 // and forwards to HISTOGRAM_POINTER_USE. 81 #define HISTOGRAM_POINTER_USE(atomic_histogram_pointer, \ 82 constant_histogram_name, \ 83 histogram_add_method_invocation, \ 84 histogram_factory_get_invocation) \ 85 do { \ 86 base::HistogramBase* histogram_pointer( \ 87 reinterpret_cast<base::HistogramBase*>( \ 88 base::subtle::Acquire_Load(atomic_histogram_pointer))); \ 89 if (!histogram_pointer) { \ 90 histogram_pointer = histogram_factory_get_invocation; \ 91 base::subtle::Release_Store( \ 92 atomic_histogram_pointer, \ 93 reinterpret_cast<base::subtle::AtomicWord>(histogram_pointer)); \ 94 } \ 95 if (DCHECK_IS_ON()) \ 96 histogram_pointer->CheckName(constant_histogram_name); \ 97 histogram_pointer->histogram_add_method_invocation; \ 98 } while (0) 99 100 // Defines the static |atomic_histogram_pointer| and forwards to 101 // HISTOGRAM_POINTER_USE. 102 #define STATIC_HISTOGRAM_POINTER_BLOCK(constant_histogram_name, \ 103 histogram_add_method_invocation, \ 104 histogram_factory_get_invocation) \ 105 do { \ 106 static base::subtle::AtomicWord atomic_histogram_pointer = 0; \ 107 HISTOGRAM_POINTER_USE(&atomic_histogram_pointer, constant_histogram_name, \ 108 histogram_add_method_invocation, \ 109 histogram_factory_get_invocation); \ 110 } while (0) 111 112 //------------------------------------------------------------------------------ 113 // Provide easy general purpose histogram in a macro, just like stats counters. 114 // Most of these macros use 50 buckets, but check the definition for details. 115 // 116 // All of these macros must be called with |name| as a runtime constant --- it 117 // doesn't have to literally be a constant, but it must be the same string on 118 // all calls from a particular call site. If this rule is violated, 119 // STATIC_HISTOGRAM_POINTER_BLOCK will DCHECK, and if DCHECKS are disabled, the 120 // data will be written to the wrong histogram. 121 122 #define LOCAL_HISTOGRAM_TIMES(name, sample) LOCAL_HISTOGRAM_CUSTOM_TIMES( \ 123 name, sample, base::TimeDelta::FromMilliseconds(1), \ 124 base::TimeDelta::FromSeconds(10), 50) 125 126 // For folks that need real specific times, use this to select a precise range 127 // of times you want plotted, and the number of buckets you want used. 128 #define LOCAL_HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \ 129 STATIC_HISTOGRAM_POINTER_BLOCK(name, AddTime(sample), \ 130 base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \ 131 base::HistogramBase::kNoFlags)) 132 133 #define LOCAL_HISTOGRAM_COUNTS(name, sample) LOCAL_HISTOGRAM_CUSTOM_COUNTS( \ 134 name, sample, 1, 1000000, 50) 135 136 #define LOCAL_HISTOGRAM_COUNTS_100(name, sample) \ 137 LOCAL_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1, 100, 50) 138 139 #define LOCAL_HISTOGRAM_COUNTS_10000(name, sample) \ 140 LOCAL_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1, 10000, 50) 141 142 #define LOCAL_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \ 143 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 144 base::Histogram::FactoryGet(name, min, max, bucket_count, \ 145 base::HistogramBase::kNoFlags)) 146 147 // This is a helper macro used by other macros and shouldn't be used directly. 148 #define HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary, flag) \ 149 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 150 base::LinearHistogram::FactoryGet(name, 1, boundary, boundary + 1, \ 151 flag)) 152 153 #define LOCAL_HISTOGRAM_PERCENTAGE(name, under_one_hundred) \ 154 LOCAL_HISTOGRAM_ENUMERATION(name, under_one_hundred, 101) 155 156 #define LOCAL_HISTOGRAM_BOOLEAN(name, sample) \ 157 STATIC_HISTOGRAM_POINTER_BLOCK(name, AddBoolean(sample), \ 158 base::BooleanHistogram::FactoryGet(name, base::Histogram::kNoFlags)) 159 160 // Support histograming of an enumerated value. The samples should always be 161 // strictly less than |boundary_value| -- this prevents you from running into 162 // problems down the line if you add additional buckets to the histogram. Note 163 // also that, despite explicitly setting the minimum bucket value to |1| below, 164 // it is fine for enumerated histograms to be 0-indexed -- this is because 165 // enumerated histograms should never have underflow. 166 #define LOCAL_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \ 167 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 168 base::LinearHistogram::FactoryGet(name, 1, boundary_value, \ 169 boundary_value + 1, base::HistogramBase::kNoFlags)) 170 171 // Support histograming of an enumerated value. Samples should be one of the 172 // std::vector<int> list provided via |custom_ranges|. See comments above 173 // CustomRanges::FactoryGet about the requirement of |custom_ranges|. 174 // You can use the helper function CustomHistogram::ArrayToCustomRanges to 175 // transform a C-style array of valid sample values to a std::vector<int>. 176 #define LOCAL_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \ 177 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 178 base::CustomHistogram::FactoryGet(name, custom_ranges, \ 179 base::HistogramBase::kNoFlags)) 180 181 #define LOCAL_HISTOGRAM_MEMORY_KB(name, sample) LOCAL_HISTOGRAM_CUSTOM_COUNTS( \ 182 name, sample, 1000, 500000, 50) 183 184 //------------------------------------------------------------------------------ 185 // The following macros provide typical usage scenarios for callers that wish 186 // to record histogram data, and have the data submitted/uploaded via UMA. 187 // Not all systems support such UMA, but if they do, the following macros 188 // should work with the service. 189 190 #define UMA_HISTOGRAM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ 191 name, sample, base::TimeDelta::FromMilliseconds(1), \ 192 base::TimeDelta::FromSeconds(10), 50) 193 194 #define UMA_HISTOGRAM_MEDIUM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ 195 name, sample, base::TimeDelta::FromMilliseconds(10), \ 196 base::TimeDelta::FromMinutes(3), 50) 197 198 // Use this macro when times can routinely be much longer than 10 seconds. 199 #define UMA_HISTOGRAM_LONG_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ 200 name, sample, base::TimeDelta::FromMilliseconds(1), \ 201 base::TimeDelta::FromHours(1), 50) 202 203 // Use this macro when times can routinely be much longer than 10 seconds and 204 // you want 100 buckets. 205 #define UMA_HISTOGRAM_LONG_TIMES_100(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ 206 name, sample, base::TimeDelta::FromMilliseconds(1), \ 207 base::TimeDelta::FromHours(1), 100) 208 209 #define UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \ 210 STATIC_HISTOGRAM_POINTER_BLOCK(name, AddTime(sample), \ 211 base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \ 212 base::HistogramBase::kUmaTargetedHistogramFlag)) 213 214 #define UMA_HISTOGRAM_COUNTS(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 215 name, sample, 1, 1000000, 50) 216 217 #define UMA_HISTOGRAM_COUNTS_100(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 218 name, sample, 1, 100, 50) 219 220 #define UMA_HISTOGRAM_COUNTS_1000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 221 name, sample, 1, 1000, 50) 222 223 #define UMA_HISTOGRAM_COUNTS_10000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 224 name, sample, 1, 10000, 50) 225 226 #define UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \ 227 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 228 base::Histogram::FactoryGet(name, min, max, bucket_count, \ 229 base::HistogramBase::kUmaTargetedHistogramFlag)) 230 231 #define UMA_HISTOGRAM_MEMORY_KB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 232 name, sample, 1000, 500000, 50) 233 234 #define UMA_HISTOGRAM_MEMORY_MB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 235 name, sample, 1, 1000, 50) 236 237 #define UMA_HISTOGRAM_MEMORY_LARGE_MB(name, sample) \ 238 UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1, 64000, 100) 239 240 #define UMA_HISTOGRAM_PERCENTAGE(name, under_one_hundred) \ 241 UMA_HISTOGRAM_ENUMERATION(name, under_one_hundred, 101) 242 243 #define UMA_HISTOGRAM_BOOLEAN(name, sample) \ 244 STATIC_HISTOGRAM_POINTER_BLOCK(name, AddBoolean(sample), \ 245 base::BooleanHistogram::FactoryGet(name, \ 246 base::HistogramBase::kUmaTargetedHistogramFlag)) 247 248 // The samples should always be strictly less than |boundary_value|. For more 249 // details, see the comment for the |LOCAL_HISTOGRAM_ENUMERATION| macro, above. 250 #define UMA_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \ 251 HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary_value, \ 252 base::HistogramBase::kUmaTargetedHistogramFlag) 253 254 // Similar to UMA_HISTOGRAM_ENUMERATION, but used for recording stability 255 // histograms. Use this if recording a histogram that should be part of the 256 // initial stability log. 257 #define UMA_STABILITY_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \ 258 HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary_value, \ 259 base::HistogramBase::kUmaStabilityHistogramFlag) 260 261 #define UMA_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \ 262 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 263 base::CustomHistogram::FactoryGet(name, custom_ranges, \ 264 base::HistogramBase::kUmaTargetedHistogramFlag)) 265 266 // Scoped class which logs its time on this earth as a UMA statistic. This is 267 // recommended for when you want a histogram which measures the time it takes 268 // for a method to execute. This measures up to 10 seconds. 269 #define SCOPED_UMA_HISTOGRAM_TIMER(name) \ 270 SCOPED_UMA_HISTOGRAM_TIMER_EXPANDER(name, false, __COUNTER__) 271 272 // Similar scoped histogram timer, but this uses UMA_HISTOGRAM_LONG_TIMES_100, 273 // which measures up to an hour, and uses 100 buckets. This is more expensive 274 // to store, so only use if this often takes >10 seconds. 275 #define SCOPED_UMA_HISTOGRAM_LONG_TIMER(name) \ 276 SCOPED_UMA_HISTOGRAM_TIMER_EXPANDER(name, true, __COUNTER__) 277 278 // This nested macro is necessary to expand __COUNTER__ to an actual value. 279 #define SCOPED_UMA_HISTOGRAM_TIMER_EXPANDER(name, is_long, key) \ 280 SCOPED_UMA_HISTOGRAM_TIMER_UNIQUE(name, is_long, key) 281 282 #define SCOPED_UMA_HISTOGRAM_TIMER_UNIQUE(name, is_long, key) \ 283 class ScopedHistogramTimer##key { \ 284 public: \ 285 ScopedHistogramTimer##key() : constructed_(base::TimeTicks::Now()) {} \ 286 ~ScopedHistogramTimer##key() { \ 287 base::TimeDelta elapsed = base::TimeTicks::Now() - constructed_; \ 288 if (is_long) { \ 289 UMA_HISTOGRAM_LONG_TIMES_100(name, elapsed); \ 290 } else { \ 291 UMA_HISTOGRAM_TIMES(name, elapsed); \ 292 } \ 293 } \ 294 private: \ 295 base::TimeTicks constructed_; \ 296 } scoped_histogram_timer_##key 297 298 #endif // BASE_METRICS_HISTOGRAM_MACROS_H_ 299