base/metrics/histogram_macros.h

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