1 // Copyright 2014 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_HISTOGRAM_MACROS_H_ 6 #define BASE_METRICS_HISTOGRAM_MACROS_H_ 7 8 #include "base/check_op.h" 9 #include "base/metrics/histogram.h" 10 #include "base/metrics/histogram_macros_internal.h" 11 #include "base/metrics/histogram_macros_local.h" 12 #include "base/time/time.h" 13 14 15 // Macros for efficient use of histograms. 16 // 17 // For best practices on deciding when to emit to a histogram and what form 18 // the histogram should take, see 19 // https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/histograms/README.md 20 21 // All of these macros must be called with |name| as a runtime constant - it 22 // doesn't have to literally be a constant, but it must be the same string on 23 // all calls from a particular call site. If this rule is violated, it is 24 // possible the data will be written to the wrong histogram. 25 26 //------------------------------------------------------------------------------ 27 // Enumeration histograms. 28 29 // These macros create histograms for enumerated data. Ideally, the data should 30 // be of the form of "event occurs, log the result". We recommended not putting 31 // related but not directly connected data as enums within the same histogram. 32 // You should be defining an associated Enum, and the input sample should be 33 // an element of the Enum. 34 // All of these macros must be called with |name| as a runtime constant. 35 36 // The first variant of UMA_HISTOGRAM_ENUMERATION accepts two arguments: the 37 // histogram name and the enum sample. It deduces the correct boundary value to 38 // use by looking for an enumerator with the name kMaxValue. kMaxValue should 39 // share the value of the highest enumerator: this avoids switch statements 40 // having to handle a sentinel no-op value. 41 // 42 // Sample usage: 43 // // These values are logged to UMA. Entries should not be renumbered and 44 // // numeric values should never be reused. Please keep in sync with "MyEnum" 45 // // in src/tools/metrics/histograms/enums.xml. 46 // enum class MyEnum { 47 // kFirstValue = 0, 48 // kSecondValue = 1, 49 // ... 50 // kFinalValue = N, 51 // kMaxValue = kFinalValue, 52 // }; 53 // UMA_HISTOGRAM_ENUMERATION("My.Enumeration", MyEnum::kSomeValue); 54 // 55 // The second variant requires three arguments: the first two are the same as 56 // before, and the third argument is the enum boundary: this must be strictly 57 // greater than any other enumerator that will be sampled. This only works for 58 // enums with a fixed underlying type. 59 // 60 // Sample usage: 61 // // These values are logged to UMA. Entries should not be renumbered and 62 // // numeric values should never be reused. Please keep in sync with "MyEnum" 63 // // in src/tools/metrics/histograms/enums.xml. 64 // enum class MyEnum : uint8_t { 65 // FIRST_VALUE = 0, 66 // SECOND_VALUE = 1, 67 // ... 68 // FINAL_VALUE = N, 69 // COUNT 70 // }; 71 // UMA_HISTOGRAM_ENUMERATION("My.Enumeration", 72 // MyEnum::SOME_VALUE, MyEnum::COUNT); 73 // 74 // Note: If the enum is used in a switch, it is often desirable to avoid writing 75 // a case statement to handle an unused sentinel value (i.e. COUNT in the above 76 // example). For scoped enums, this is awkward since it requires casting the 77 // enum to an arithmetic type and adding one. Instead, prefer the two argument 78 // version of the macro which automatically deduces the boundary from kMaxValue. 79 #define UMA_HISTOGRAM_ENUMERATION(name, ...) \ 80 INTERNAL_UMA_HISTOGRAM_ENUMERATION_GET_MACRO( \ 81 __VA_ARGS__, INTERNAL_UMA_HISTOGRAM_ENUMERATION_SPECIFY_BOUNDARY, \ 82 INTERNAL_UMA_HISTOGRAM_ENUMERATION_DEDUCE_BOUNDARY) \ 83 (name, __VA_ARGS__, base::HistogramBase::kUmaTargetedHistogramFlag) 84 85 // As above but "scaled" count to avoid overflows caused by increments of 86 // large amounts. See UMA_HISTOGRAM_SCALED_EXACT_LINEAR for more information. 87 // Only the new format utilizing an internal kMaxValue is supported. 88 // It'll be necessary to #include "base/lazy_instance.h" to use this macro. 89 // name: Full constant name of the histogram (must not change between calls). 90 // sample: Bucket to be incremented. 91 // count: Amount by which to increment. 92 // scale: Amount by which |count| is divided. 93 94 // Sample usage: 95 // UMA_HISTOGRAM_SCALED_ENUMERATION("FooKiB", kEnumValue, byte_count, 1024) 96 #define UMA_HISTOGRAM_SCALED_ENUMERATION(name, sample, count, scale) \ 97 INTERNAL_HISTOGRAM_SCALED_ENUMERATION_WITH_FLAG( \ 98 name, sample, count, scale, \ 99 base::HistogramBase::kUmaTargetedHistogramFlag) 100 101 // Histogram for boolean values. 102 103 // Sample usage: 104 // UMA_HISTOGRAM_BOOLEAN("Histogram.Boolean", bool); 105 #define UMA_HISTOGRAM_BOOLEAN(name, sample) \ 106 STATIC_HISTOGRAM_POINTER_BLOCK(name, AddBoolean(sample), \ 107 base::BooleanHistogram::FactoryGet(name, \ 108 base::HistogramBase::kUmaTargetedHistogramFlag)) 109 110 //------------------------------------------------------------------------------ 111 // Linear histograms. 112 113 // All of these macros must be called with |name| as a runtime constant. 114 115 // For numeric measurements where you want exact integer values up to 116 // |exclusive_max|. |exclusive_max| itself is included in the overflow bucket. 117 // Therefore, if you want an accurate measure up to kMax, then |exclusive_max| 118 // should be set to kMax + 1. 119 // 120 // |exclusive_max| should be 101 or less. If you need to capture a larger range, 121 // we recommend the use of the COUNT histograms below. 122 // 123 // Sample usage: 124 // base::UmaHistogramExactLinear("Histogram.Linear", sample, kMax + 1); 125 // In this case, buckets are 1, 2, .., kMax, kMax+1, where the kMax+1 bucket 126 // captures everything kMax+1 and above. 127 #define UMA_HISTOGRAM_EXACT_LINEAR(name, sample, exclusive_max) \ 128 INTERNAL_HISTOGRAM_EXACT_LINEAR_WITH_FLAG( \ 129 name, sample, exclusive_max, \ 130 base::HistogramBase::kUmaTargetedHistogramFlag) 131 132 // Used for capturing basic percentages. This will be 100 buckets of size 1. 133 134 // Sample usage: 135 // UMA_HISTOGRAM_PERCENTAGE("Histogram.Percent", percent_as_int); 136 #define UMA_HISTOGRAM_PERCENTAGE(name, percent_as_int) \ 137 UMA_HISTOGRAM_EXACT_LINEAR(name, percent_as_int, 101) 138 139 //------------------------------------------------------------------------------ 140 // Scaled linear histograms. 141 142 // These take |count| and |scale| parameters to allow cumulative reporting of 143 // large numbers. For example, code might pass a count of 1825 bytes and a scale 144 // of 1024 bytes to report values in kilobytes. Only the scaled count is 145 // reported, but the remainder is tracked between calls, so that multiple calls 146 // will accumulate correctly. 147 // It'll be necessary to #include "base/lazy_instance.h" to use this macro. 148 // name: Full constant name of the histogram (must not change between calls). 149 // sample: Bucket to be incremented. 150 // count: Amount by which to increment. 151 // sample_max: Maximum (exclusive) allowed sample value. 152 // scale: Amount by which |count| is divided. 153 154 // Sample usage: 155 // UMA_HISTOGRAM_SCALED_EXACT_LINER("FooKiB", bucket_no, byte_count, 156 // kBucketsMax+1, 1024) 157 #define UMA_HISTOGRAM_SCALED_EXACT_LINEAR(name, sample, count, sample_max, \ 158 scale) \ 159 INTERNAL_HISTOGRAM_SCALED_EXACT_LINEAR_WITH_FLAG( \ 160 name, sample, count, sample_max, scale, \ 161 base::HistogramBase::kUmaTargetedHistogramFlag) 162 163 //------------------------------------------------------------------------------ 164 // Count histograms. These are used for collecting numeric data. Note that we 165 // have macros for more specialized use cases below (memory, time, percentages). 166 167 // The number suffixes here refer to the max size of the sample, i.e. COUNT_1000 168 // will be able to collect samples of counts up to 1000. The default number of 169 // buckets in all default macros is 50. We recommend erring on the side of too 170 // large a range versus too short a range. 171 // These macros default to exponential histograms - i.e. the lengths of the 172 // bucket ranges exponentially increase as the sample range increases. 173 // These should *not* be used if you are interested in exact counts, i.e. a 174 // bucket range of 1. In these cases, you should use the ENUMERATION macros 175 // defined later. These should also not be used to capture the number of some 176 // event, i.e. "button X was clicked N times". In this cases, an enum should be 177 // used, ideally with an appropriate baseline enum entry included. 178 // All of these macros must be called with |name| as a runtime constant. 179 180 // Sample usage: 181 // UMA_HISTOGRAM_COUNTS_1M("My.Histogram", sample); 182 183 #define UMA_HISTOGRAM_COUNTS_100(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 184 name, sample, 1, 100, 50) 185 186 #define UMA_HISTOGRAM_COUNTS_1000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 187 name, sample, 1, 1000, 50) 188 189 #define UMA_HISTOGRAM_COUNTS_10000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 190 name, sample, 1, 10000, 50) 191 192 #define UMA_HISTOGRAM_COUNTS_100000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 193 name, sample, 1, 100000, 50) 194 195 #define UMA_HISTOGRAM_COUNTS_1M(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 196 name, sample, 1, 1000000, 50) 197 198 #define UMA_HISTOGRAM_COUNTS_10M(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 199 name, sample, 1, 10000000, 50) 200 201 // This macro allows the min, max, and number of buckets to be customized. Any 202 // samples whose values are outside of [min, exclusive_max-1] are put in the 203 // underflow or overflow buckets. Note that |min| should be >=1 as emitted 0s go 204 // into the underflow bucket. 205 206 // Sample usage: 207 // UMA_HISTOGRAM_CUSTOM_COUNTS("My.Histogram", sample, 1, 100000000, 50); 208 #define UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, exclusive_max, \ 209 bucket_count) \ 210 INTERNAL_HISTOGRAM_CUSTOM_COUNTS_WITH_FLAG( \ 211 name, sample, min, exclusive_max, bucket_count, \ 212 base::HistogramBase::kUmaTargetedHistogramFlag) 213 214 //------------------------------------------------------------------------------ 215 // Timing histograms. These are used for collecting timing data (generally 216 // latencies). 217 218 // These macros create exponentially sized histograms (lengths of the bucket 219 // ranges exponentially increase as the sample range increases). The input 220 // sample is a base::TimeDelta. The output data is measured in ms granularity. 221 // All of these macros must be called with |name| as a runtime constant. 222 223 // Sample usage: 224 // UMA_HISTOGRAM_TIMES("My.Timing.Histogram", time_delta); 225 226 // Short timings - up to 10 seconds. For high-resolution (microseconds) timings, 227 // see UMA_HISTOGRAM_CUSTOM_MICROSECONDS_TIMES. 228 #define UMA_HISTOGRAM_TIMES(name, sample) \ 229 UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, base::Milliseconds(1), \ 230 base::Seconds(10), 50) 231 232 // Medium timings - up to 3 minutes. Note this starts at 10ms (no good reason, 233 // but not worth changing). 234 #define UMA_HISTOGRAM_MEDIUM_TIMES(name, sample) \ 235 UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, base::Milliseconds(10), \ 236 base::Minutes(3), 50) 237 238 // Long timings - up to an hour. 239 #define UMA_HISTOGRAM_LONG_TIMES(name, sample) \ 240 UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, base::Milliseconds(1), \ 241 base::Hours(1), 50) 242 243 // Long timings with higher granularity - up to an hour with 100 buckets. 244 #define UMA_HISTOGRAM_LONG_TIMES_100(name, sample) \ 245 UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, base::Milliseconds(1), \ 246 base::Hours(1), 100) 247 248 // This can be used when the default ranges are not sufficient. This macro lets 249 // the metric developer customize the min and max of the sampled range, as well 250 // as the number of buckets recorded. 251 252 // Sample usage: 253 // UMA_HISTOGRAM_CUSTOM_TIMES("Very.Long.Timing.Histogram", time_delta, 254 // base::Seconds(1), base::Days(1), 100); 255 #define UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \ 256 STATIC_HISTOGRAM_POINTER_BLOCK( \ 257 name, AddTimeMillisecondsGranularity(sample), \ 258 base::Histogram::FactoryTimeGet( \ 259 name, min, max, bucket_count, \ 260 base::HistogramBase::kUmaTargetedHistogramFlag)) 261 262 // Same as UMA_HISTOGRAM_CUSTOM_TIMES but reports |sample| in microseconds, 263 // dropping the report if this client doesn't have a high-resolution clock. 264 // 265 // Note: dropping reports on clients with low-resolution clocks means these 266 // reports will be biased to a portion of the population on Windows. See 267 // Windows.HasHighResolutionTimeTicks for the affected sample. 268 // 269 // Sample usage: 270 // UMA_HISTOGRAM_CUSTOM_MICROSECONDS_TIMES( 271 // "High.Resolution.TimingMicroseconds.Histogram", time_delta, 272 // base::Microseconds(1), 273 // base::Milliseconds(10), 100); 274 #define UMA_HISTOGRAM_CUSTOM_MICROSECONDS_TIMES(name, sample, min, max, \ 275 bucket_count) \ 276 STATIC_HISTOGRAM_POINTER_BLOCK( \ 277 name, AddTimeMicrosecondsGranularity(sample), \ 278 base::Histogram::FactoryMicrosecondsTimeGet( \ 279 name, min, max, bucket_count, \ 280 base::HistogramBase::kUmaTargetedHistogramFlag)) 281 282 // Scoped class which logs its time on this earth in milliseconds as a UMA 283 // statistic. This is recommended for when you want a histogram which measures 284 // the time it takes for a method to execute. This measures up to 10 seconds. It 285 // uses UMA_HISTOGRAM_TIMES under the hood. 286 287 // Sample usage: 288 // void Function() { 289 // SCOPED_UMA_HISTOGRAM_TIMER("Component.FunctionTime"); 290 // ... 291 // } 292 enum class ScopedHistogramTiming { 293 kMicrosecondTimes, 294 kMediumTimes, 295 kLongTimes 296 }; 297 #define SCOPED_UMA_HISTOGRAM_TIMER(name) \ 298 INTERNAL_SCOPED_UMA_HISTOGRAM_TIMER_EXPANDER( \ 299 name, ScopedHistogramTiming::kMediumTimes, __COUNTER__) 300 301 // Similar scoped histogram timer, but this uses UMA_HISTOGRAM_LONG_TIMES_100, 302 // which measures up to an hour, and uses 100 buckets. This is more expensive 303 // to store, so only use if this often takes >10 seconds. 304 #define SCOPED_UMA_HISTOGRAM_LONG_TIMER(name) \ 305 INTERNAL_SCOPED_UMA_HISTOGRAM_TIMER_EXPANDER( \ 306 name, ScopedHistogramTiming::kLongTimes, __COUNTER__) 307 308 // Similar scoped histogram timer, but this uses 309 // UMA_HISTOGRAM_CUSTOM_MICROSECONDS_TIMES, measuring from 1 microseconds to 1 310 // second, with 50 buckets. 311 #define SCOPED_UMA_HISTOGRAM_TIMER_MICROS(name) \ 312 INTERNAL_SCOPED_UMA_HISTOGRAM_TIMER_EXPANDER( \ 313 name, ScopedHistogramTiming::kMicrosecondTimes, __COUNTER__) 314 315 //------------------------------------------------------------------------------ 316 // Memory histograms. 317 318 // These macros create exponentially sized histograms (lengths of the bucket 319 // ranges exponentially increase as the sample range increases). The input 320 // sample must be a number measured in kilobytes. 321 // All of these macros must be called with |name| as a runtime constant. 322 323 // Sample usage: 324 // UMA_HISTOGRAM_MEMORY_KB("My.Memory.Histogram", memory_in_kb); 325 326 // Used to measure common KB-granularity memory stats. Range is up to 500000KB - 327 // approximately 500M. 328 #define UMA_HISTOGRAM_MEMORY_KB(name, sample) \ 329 UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1000, 500000, 50) 330 331 // Used to measure common MB-granularity memory stats. Range is up to 4000MiB - 332 // approximately 4GiB. 333 #define UMA_HISTOGRAM_MEMORY_MEDIUM_MB(name, sample) \ 334 UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1, 4000, 100) 335 336 // Used to measure common MB-granularity memory stats. Range is up to ~64G. 337 #define UMA_HISTOGRAM_MEMORY_LARGE_MB(name, sample) \ 338 UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1, 64000, 100) 339 340 341 //------------------------------------------------------------------------------ 342 // Stability-specific histograms. 343 344 // Histograms logged in as stability histograms will be included in the initial 345 // stability log. See comments by declaration of 346 // MetricsService::PrepareInitialStabilityLog(). 347 // All of these macros must be called with |name| as a runtime constant. 348 349 // For details on usage, see the documentation on the non-stability equivalents. 350 351 #define UMA_STABILITY_HISTOGRAM_BOOLEAN(name, sample) \ 352 STATIC_HISTOGRAM_POINTER_BLOCK( \ 353 name, AddBoolean(sample), \ 354 base::BooleanHistogram::FactoryGet( \ 355 name, base::HistogramBase::kUmaStabilityHistogramFlag)) 356 357 #define UMA_STABILITY_HISTOGRAM_COUNTS_100(name, sample) \ 358 UMA_STABILITY_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1, 100, 50) 359 360 #define UMA_STABILITY_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, \ 361 bucket_count) \ 362 INTERNAL_HISTOGRAM_CUSTOM_COUNTS_WITH_FLAG( \ 363 name, sample, min, max, bucket_count, \ 364 base::HistogramBase::kUmaStabilityHistogramFlag) 365 366 #define UMA_STABILITY_HISTOGRAM_ENUMERATION(name, ...) \ 367 INTERNAL_UMA_HISTOGRAM_ENUMERATION_GET_MACRO( \ 368 __VA_ARGS__, INTERNAL_UMA_HISTOGRAM_ENUMERATION_SPECIFY_BOUNDARY, \ 369 INTERNAL_UMA_HISTOGRAM_ENUMERATION_DEDUCE_BOUNDARY) \ 370 (name, __VA_ARGS__, base::HistogramBase::kUmaStabilityHistogramFlag) 371 372 #define UMA_STABILITY_HISTOGRAM_LONG_TIMES(name, sample) \ 373 STATIC_HISTOGRAM_POINTER_BLOCK( \ 374 name, AddTimeMillisecondsGranularity(sample), \ 375 base::Histogram::FactoryTimeGet( \ 376 name, base::Milliseconds(1), base::Hours(1), 50, \ 377 base::HistogramBase::kUmaStabilityHistogramFlag)) 378 379 #define UMA_STABILITY_HISTOGRAM_PERCENTAGE(name, percent_as_int) \ 380 INTERNAL_HISTOGRAM_EXACT_LINEAR_WITH_FLAG( \ 381 name, percent_as_int, 101, \ 382 base::HistogramBase::kUmaStabilityHistogramFlag) 383 384 //------------------------------------------------------------------------------ 385 // Sparse histograms. 386 // 387 // The |sample| can be a negative or non-negative number. 388 // 389 // Sparse histograms are well suited for recording counts of exact sample values 390 // that are sparsely distributed over a relatively large range, in cases where 391 // ultra-fast performance is not critical. For instance, Sqlite.Version.* are 392 // sparse because for any given database, there's going to be exactly one 393 // version logged. 394 // 395 // For important details on performance, data size, and usage, see the 396 // documentation on the regular function equivalents (histogram_functions.h). 397 #define UMA_HISTOGRAM_SPARSE(name, sample) \ 398 STATIC_HISTOGRAM_POINTER_BLOCK( \ 399 name, Add(sample), \ 400 base::SparseHistogram::FactoryGet( \ 401 name, base::HistogramBase::kUmaTargetedHistogramFlag)) 402 403 //------------------------------------------------------------------------------ 404 // Histogram instantiation helpers. 405 406 // Support a collection of histograms, perhaps one for each entry in an 407 // enumeration. This macro manages a block of pointers, adding to a specific 408 // one by its index. 409 // 410 // A typical instantiation looks something like this: 411 // STATIC_HISTOGRAM_POINTER_GROUP( 412 // GetHistogramNameForIndex(histogram_index), 413 // histogram_index, MAXIMUM_HISTOGRAM_INDEX, Add(some_delta), 414 // base::Histogram::FactoryGet( 415 // GetHistogramNameForIndex(histogram_index), 416 // MINIMUM_SAMPLE, MAXIMUM_SAMPLE, BUCKET_COUNT, 417 // base::HistogramBase::kUmaTargetedHistogramFlag)); 418 // 419 // Though it seems inefficient to generate the name twice, the first 420 // instance will be used only for DCHECK builds and the second will 421 // execute only during the first access to the given index, after which 422 // the pointer is cached and the name never needed again. 423 #define STATIC_HISTOGRAM_POINTER_GROUP( \ 424 constant_histogram_name, index, constant_maximum, \ 425 histogram_add_method_invocation, histogram_factory_get_invocation) \ 426 do { \ 427 static std::atomic_uintptr_t atomic_histograms[constant_maximum]; \ 428 DCHECK_LE(0, index); \ 429 DCHECK_LT(index, constant_maximum); \ 430 HISTOGRAM_POINTER_USE( \ 431 std::addressof(atomic_histograms[index]), constant_histogram_name, \ 432 histogram_add_method_invocation, histogram_factory_get_invocation); \ 433 } while (0) 434 435 //------------------------------------------------------------------------------ 436 // Deprecated histogram macros. Not recommended for current use. 437 438 // Legacy name for UMA_HISTOGRAM_COUNTS_1M. Suggest using explicit naming 439 // and not using this macro going forward. 440 #define UMA_HISTOGRAM_COUNTS(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 441 name, sample, 1, 1000000, 50) 442 443 // MB-granularity memory metric. This has a short max (1G). 444 #define UMA_HISTOGRAM_MEMORY_MB(name, sample) \ 445 UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1, 1000, 50) 446 447 // For an enum with customized range. In general, sparse histograms should be 448 // used instead. 449 // Samples should be one of the std::vector<int> list provided via 450 // |custom_ranges|. See comments above CustomRanges::FactoryGet about the 451 // requirement of |custom_ranges|. You can use the helper function 452 // CustomHistogram::ArrayToCustomEnumRanges to transform a C-style array of 453 // valid sample values to a std::vector<int>. 454 #define UMA_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \ 455 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 456 base::CustomHistogram::FactoryGet(name, custom_ranges, \ 457 base::HistogramBase::kUmaTargetedHistogramFlag)) 458 459 #endif // BASE_METRICS_HISTOGRAM_MACROS_H_ 460