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(&atomic_histogram_pointer, \
  82           reinterpret_cast<base::subtle::AtomicWord>(histogram_pointer)); \
  83     } \
  84     if (DCHECK_IS_ON) \
  85       histogram_pointer->CheckName(constant_histogram_name); \
  86     histogram_pointer->histogram_add_method_invocation; \
  87   } while (0)
  88
  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_10000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
 193     name, sample, 1, 10000, 50)
 194
 195 #define UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \
 196     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
 197         base::Histogram::FactoryGet(name, min, max, bucket_count, \
 198             base::HistogramBase::kUmaTargetedHistogramFlag))
 199
 200 #define UMA_HISTOGRAM_MEMORY_KB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
 201     name, sample, 1000, 500000, 50)
 202
 203 #define UMA_HISTOGRAM_MEMORY_MB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
 204     name, sample, 1, 1000, 50)
 205
 206 #define UMA_HISTOGRAM_PERCENTAGE(name, under_one_hundred) \
 207     UMA_HISTOGRAM_ENUMERATION(name, under_one_hundred, 101)
 208
 209 #define UMA_HISTOGRAM_BOOLEAN(name, sample) \
 210     STATIC_HISTOGRAM_POINTER_BLOCK(name, AddBoolean(sample), \
 211         base::BooleanHistogram::FactoryGet(name, \
 212             base::HistogramBase::kUmaTargetedHistogramFlag))
 213
 214 // The samples should always be strictly less than |boundary_value|.  For more
 215 // details, see the comment for the |LOCAL_HISTOGRAM_ENUMERATION| macro, above.
 216 #define UMA_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \
 217     HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary_value, \
 218         base::HistogramBase::kUmaTargetedHistogramFlag)
 219
 220 // Similar to UMA_HISTOGRAM_ENUMERATION, but used for recording stability
 221 // histograms.  Use this if recording a histogram that should be part of the
 222 // initial stability log.
 223 #define UMA_STABILITY_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \
 224     HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary_value, \
 225         base::HistogramBase::kUmaStabilityHistogramFlag)
 226
 227 #define UMA_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \
 228     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
 229         base::CustomHistogram::FactoryGet(name, custom_ranges, \
 230             base::HistogramBase::kUmaTargetedHistogramFlag))
 231
 232 #endif  // BASE_METRICS_HISTOGRAM_MACROS_H_