src/base/metrics/histogram.h

   1 // Copyright (c) 2012 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 // Histogram is an object that aggregates statistics, and can summarize them in
   6 // various forms, including ASCII graphical, HTML, and numerically (as a
   7 // vector of numbers corresponding to each of the aggregating buckets).
   8
   9 // It supports calls to accumulate either time intervals (which are processed
  10 // as integral number of milliseconds), or arbitrary integral units.
  11
  12 // For Histogram(exponential histogram), LinearHistogram and CustomHistogram,
  13 // the minimum for a declared range is 1 (instead of 0), while the maximum is
  14 // (HistogramBase::kSampleType_MAX - 1). Currently you can declare histograms
  15 // with ranges exceeding those limits (e.g. 0 as minimal or
  16 // HistogramBase::kSampleType_MAX as maximal), but those excesses will be
  17 // silently clamped to those limits (for backwards compatibility with existing
  18 // code). Best practice is to not exceed the limits.
  19
  20 // Each use of a histogram with the same name will reference the same underlying
  21 // data, so it is safe to record to the same histogram from multiple locations
  22 // in the code. It is a runtime error if all uses of the same histogram do not
  23 // agree exactly in type, bucket size and range.
  24
  25 // For Histogram and LinearHistogram, the maximum for a declared range should
  26 // always be larger (not equal) than minmal range. Zero and
  27 // HistogramBase::kSampleType_MAX are implicitly added as first and last ranges,
  28 // so the smallest legal bucket_count is 3. However CustomHistogram can have
  29 // bucket count as 2 (when you give a custom ranges vector containing only 1
  30 // range).
  31 // For these 3 kinds of histograms, the max bucket count is always
  32 // (Histogram::kBucketCount_MAX - 1).
  33
  34 // The buckets layout of class Histogram is exponential. For example, buckets
  35 // might contain (sequentially) the count of values in the following intervals:
  36 // [0,1), [1,2), [2,4), [4,8), [8,16), [16,32), [32,64), [64,infinity)
  37 // That bucket allocation would actually result from construction of a histogram
  38 // for values between 1 and 64, with 8 buckets, such as:
  39 // Histogram count("some name", 1, 64, 8);
  40 // Note that the underflow bucket [0,1) and the overflow bucket [64,infinity)
  41 // are also counted by the constructor in the user supplied "bucket_count"
  42 // argument.
  43 // The above example has an exponential ratio of 2 (doubling the bucket width
  44 // in each consecutive bucket.  The Histogram class automatically calculates
  45 // the smallest ratio that it can use to construct the number of buckets
  46 // selected in the constructor.  An another example, if you had 50 buckets,
  47 // and millisecond time values from 1 to 10000, then the ratio between
  48 // consecutive bucket widths will be approximately somewhere around the 50th
  49 // root of 10000.  This approach provides very fine grain (narrow) buckets
  50 // at the low end of the histogram scale, but allows the histogram to cover a
  51 // gigantic range with the addition of very few buckets.
  52
  53 // Usually we use macros to define and use a histogram. These macros use a
  54 // pattern involving a function static variable, that is a pointer to a
  55 // histogram.  This static is explicitly initialized on any thread
  56 // that detects a uninitialized (NULL) pointer.  The potentially racy
  57 // initialization is not a problem as it is always set to point to the same
  58 // value (i.e., the FactoryGet always returns the same value).  FactoryGet
  59 // is also completely thread safe, which results in a completely thread safe,
  60 // and relatively fast, set of counters.  To avoid races at shutdown, the static
  61 // pointer is NOT deleted, and we leak the histograms at process termination.
  62
  63 #ifndef BASE_METRICS_HISTOGRAM_H_
  64 #define BASE_METRICS_HISTOGRAM_H_
  65
  66 #include <map>
  67 #include <string>
  68 #include <vector>
  69
  70 #include "base/atomicops.h"
  71 #include "base/base_export.h"
  72 #include "base/basictypes.h"
  73 #include "base/compiler_specific.h"
  74 #include "base/gtest_prod_util.h"
  75 #include "base/logging.h"
  76 #include "base/memory/scoped_ptr.h"
  77 #include "base/metrics/bucket_ranges.h"
  78 #include "base/metrics/histogram_base.h"
  79 #include "base/metrics/histogram_samples.h"
  80 #include "base/time/time.h"
  81
  82 class Pickle;
  83 class PickleIterator;
  84
  85 namespace base {
  86
  87 class Lock;
  88 //------------------------------------------------------------------------------
  89 // Histograms are often put in areas where they are called many many times, and
  90 // performance is critical.  As a result, they are designed to have a very low
  91 // recurring cost of executing (adding additional samples).  Toward that end,
  92 // the macros declare a static pointer to the histogram in question, and only
  93 // take a "slow path" to construct (or find) the histogram on the first run
  94 // through the macro.  We leak the histograms at shutdown time so that we don't
  95 // have to validate using the pointers at any time during the running of the
  96 // process.
  97
  98 // The following code is generally what a thread-safe static pointer
  99 // initializaion looks like for a histogram (after a macro is expanded).  This
 100 // sample is an expansion (with comments) of the code for
 101 // HISTOGRAM_CUSTOM_COUNTS().
 102
 103 /*
 104   do {
 105     // The pointer's presence indicates the initialization is complete.
 106     // Initialization is idempotent, so it can safely be atomically repeated.
 107     static base::subtle::AtomicWord atomic_histogram_pointer = 0;
 108
 109     // Acquire_Load() ensures that we acquire visibility to the pointed-to data
 110     // in the histogrom.
 111     base::Histogram* histogram_pointer(reinterpret_cast<base::Histogram*>(
 112         base::subtle::Acquire_Load(&atomic_histogram_pointer)));
 113
 114     if (!histogram_pointer) {
 115       // This is the slow path, which will construct OR find the matching
 116       // histogram.  FactoryGet includes locks on a global histogram name map
 117       // and is completely thread safe.
 118       histogram_pointer = base::Histogram::FactoryGet(
 119           name, min, max, bucket_count, base::HistogramBase::kNoFlags);
 120
 121       // Use Release_Store to ensure that the histogram data is made available
 122       // globally before we make the pointer visible.
 123       // Several threads may perform this store, but the same value will be
 124       // stored in all cases (for a given named/spec'ed histogram).
 125       // We could do this without any barrier, since FactoryGet entered and
 126       // exited a lock after construction, but this barrier makes things clear.
 127       base::subtle::Release_Store(&atomic_histogram_pointer,
 128           reinterpret_cast<base::subtle::AtomicWord>(histogram_pointer));
 129     }
 130
 131     // Ensure calling contract is upheld, and the name does NOT vary.
 132     DCHECK(histogram_pointer->histogram_name() == constant_histogram_name);
 133
 134     histogram_pointer->Add(sample);
 135   } while (0);
 136 */
 137
 138 // The above pattern is repeated in several macros.  The only elements that
 139 // vary are the invocation of the Add(sample) vs AddTime(sample), and the choice
 140 // of which FactoryGet method to use.  The different FactoryGet methods have
 141 // various argument lists, so the function with its argument list is provided as
 142 // a macro argument here.  The name is only used in a DCHECK, to assure that
 143 // callers don't try to vary the name of the histogram (which would tend to be
 144 // ignored by the one-time initialization of the histogtram_pointer).
 145 #define STATIC_HISTOGRAM_POINTER_BLOCK(constant_histogram_name, \
 146                                        histogram_add_method_invocation, \
 147                                        histogram_factory_get_invocation) \
 148   do { \
 149     static base::subtle::AtomicWord atomic_histogram_pointer = 0; \
 150     base::HistogramBase* histogram_pointer( \
 151         reinterpret_cast<base::HistogramBase*>( \
 152             base::subtle::Acquire_Load(&atomic_histogram_pointer))); \
 153     if (!histogram_pointer) { \
 154       histogram_pointer = histogram_factory_get_invocation; \
 155       base::subtle::Release_Store(&atomic_histogram_pointer, \
 156           reinterpret_cast<base::subtle::AtomicWord>(histogram_pointer)); \
 157     } \
 158     DCHECK_EQ(histogram_pointer->histogram_name(), \
 159               std::string(constant_histogram_name)); \
 160     histogram_pointer->histogram_add_method_invocation; \
 161   } while (0)
 162
 163
 164 //------------------------------------------------------------------------------
 165 // Provide easy general purpose histogram in a macro, just like stats counters.
 166 // The first four macros use 50 buckets.
 167
 168 #define HISTOGRAM_TIMES(name, sample) HISTOGRAM_CUSTOM_TIMES( \
 169     name, sample, base::TimeDelta::FromMilliseconds(1), \
 170     base::TimeDelta::FromSeconds(10), 50)
 171
 172 // For folks that need real specific times, use this to select a precise range
 173 // of times you want plotted, and the number of buckets you want used.
 174 #define HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \
 175     STATIC_HISTOGRAM_POINTER_BLOCK(name, AddTime(sample), \
 176         base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \
 177                                         base::HistogramBase::kNoFlags))
 178
 179 #define HISTOGRAM_COUNTS(name, sample) HISTOGRAM_CUSTOM_COUNTS( \
 180     name, sample, 1, 1000000, 50)
 181
 182 #define HISTOGRAM_COUNTS_100(name, sample) HISTOGRAM_CUSTOM_COUNTS( \
 183     name, sample, 1, 100, 50)
 184
 185 #define HISTOGRAM_COUNTS_10000(name, sample) HISTOGRAM_CUSTOM_COUNTS( \
 186     name, sample, 1, 10000, 50)
 187
 188 #define HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \
 189     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
 190         base::Histogram::FactoryGet(name, min, max, bucket_count, \
 191                                     base::HistogramBase::kNoFlags))
 192
 193 #define HISTOGRAM_PERCENTAGE(name, under_one_hundred) \
 194     HISTOGRAM_ENUMERATION(name, under_one_hundred, 101)
 195
 196 #define HISTOGRAM_BOOLEAN(name, sample) \
 197     STATIC_HISTOGRAM_POINTER_BLOCK(name, AddBoolean(sample), \
 198         base::BooleanHistogram::FactoryGet(name, base::Histogram::kNoFlags))
 199
 200 // Support histograming of an enumerated value.  The samples should always be
 201 // strictly less than |boundary_value| -- this prevents you from running into
 202 // problems down the line if you add additional buckets to the histogram.  Note
 203 // also that, despite explicitly setting the minimum bucket value to |1| below,
 204 // it is fine for enumerated histograms to be 0-indexed -- this is because
 205 // enumerated histograms should never have underflow.
 206 #define HISTOGRAM_ENUMERATION(name, sample, boundary_value) \
 207     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
 208         base::LinearHistogram::FactoryGet(name, 1, boundary_value, \
 209             boundary_value + 1, base::HistogramBase::kNoFlags))
 210
 211 // Support histograming of an enumerated value. Samples should be one of the
 212 // std::vector<int> list provided via |custom_ranges|. See comments above
 213 // CustomRanges::FactoryGet about the requirement of |custom_ranges|.
 214 // You can use the helper function CustomHistogram::ArrayToCustomRanges to
 215 // transform a C-style array of valid sample values to a std::vector<int>.
 216 #define HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \
 217     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
 218         base::CustomHistogram::FactoryGet(name, custom_ranges, \
 219                                           base::HistogramBase::kNoFlags))
 220
 221 #define HISTOGRAM_MEMORY_KB(name, sample) HISTOGRAM_CUSTOM_COUNTS( \
 222     name, sample, 1000, 500000, 50)
 223
 224 //------------------------------------------------------------------------------
 225 // Define Debug vs non-debug flavors of macros.
 226 #ifndef NDEBUG
 227
 228 #define DHISTOGRAM_TIMES(name, sample) HISTOGRAM_TIMES(name, sample)
 229 #define DHISTOGRAM_COUNTS(name, sample) HISTOGRAM_COUNTS(name, sample)
 230 #define DHISTOGRAM_PERCENTAGE(name, under_one_hundred) HISTOGRAM_PERCENTAGE(\
 231     name, under_one_hundred)
 232 #define DHISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \
 233     HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count)
 234 #define DHISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) \
 235     HISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count)
 236 #define DHISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \
 237     HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count)
 238 #define DHISTOGRAM_ENUMERATION(name, sample, boundary_value) \
 239     HISTOGRAM_ENUMERATION(name, sample, boundary_value)
 240 #define DHISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \
 241     HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges)
 242
 243 #else  // NDEBUG
 244 // Keep a mention of passed variables to avoid unused variable warnings in
 245 // release build if these variables are only used in macros.
 246 #define DISCARD_2_ARGUMENTS(a, b) \
 247   while (0) { \
 248     static_cast<void>(a); \
 249     static_cast<void>(b); \
 250  }
 251 #define DISCARD_3_ARGUMENTS(a, b, c) \
 252   while (0) { \
 253     static_cast<void>(a); \
 254     static_cast<void>(b); \
 255     static_cast<void>(c); \
 256  }
 257 #define DISCARD_5_ARGUMENTS(a, b, c, d ,e) \
 258   while (0) { \
 259     static_cast<void>(a); \
 260     static_cast<void>(b); \
 261     static_cast<void>(c); \
 262     static_cast<void>(d); \
 263     static_cast<void>(e); \
 264  }
 265 #define DHISTOGRAM_TIMES(name, sample) \
 266     DISCARD_2_ARGUMENTS(name, sample)
 267
 268 #define DHISTOGRAM_COUNTS(name, sample) \
 269     DISCARD_2_ARGUMENTS(name, sample)
 270
 271 #define DHISTOGRAM_PERCENTAGE(name, under_one_hundred) \
 272     DISCARD_2_ARGUMENTS(name, under_one_hundred)
 273
 274 #define DHISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \
 275     DISCARD_5_ARGUMENTS(name, sample, min, max, bucket_count)
 276
 277 #define DHISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) \
 278     DISCARD_5_ARGUMENTS(name, sample, min, max, bucket_count)
 279
 280 #define DHISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \
 281     DISCARD_5_ARGUMENTS(name, sample, min, max, bucket_count)
 282
 283 #define DHISTOGRAM_ENUMERATION(name, sample, boundary_value) \
 284     DISCARD_3_ARGUMENTS(name, sample, boundary_value)
 285
 286 #define DHISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \
 287     DISCARD_3_ARGUMENTS(name, sample, custom_ranges)
 288
 289 #endif  // NDEBUG
 290
 291 //------------------------------------------------------------------------------
 292 // The following macros provide typical usage scenarios for callers that wish
 293 // to record histogram data, and have the data submitted/uploaded via UMA.
 294 // Not all systems support such UMA, but if they do, the following macros
 295 // should work with the service.
 296
 297 #define UMA_HISTOGRAM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \
 298     name, sample, base::TimeDelta::FromMilliseconds(1), \
 299     base::TimeDelta::FromSeconds(10), 50)
 300
 301 #define UMA_HISTOGRAM_MEDIUM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \
 302     name, sample, base::TimeDelta::FromMilliseconds(10), \
 303     base::TimeDelta::FromMinutes(3), 50)
 304
 305 // Use this macro when times can routinely be much longer than 10 seconds.
 306 #define UMA_HISTOGRAM_LONG_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \
 307     name, sample, base::TimeDelta::FromMilliseconds(1), \
 308     base::TimeDelta::FromHours(1), 50)
 309
 310 // Use this macro when times can routinely be much longer than 10 seconds and
 311 // you want 100 buckets.
 312 #define UMA_HISTOGRAM_LONG_TIMES_100(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \
 313     name, sample, base::TimeDelta::FromMilliseconds(1), \
 314     base::TimeDelta::FromHours(1), 100)
 315
 316 #define UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \
 317     STATIC_HISTOGRAM_POINTER_BLOCK(name, AddTime(sample), \
 318         base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \
 319             base::HistogramBase::kUmaTargetedHistogramFlag))
 320
 321 #define UMA_HISTOGRAM_COUNTS(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
 322     name, sample, 1, 1000000, 50)
 323
 324 #define UMA_HISTOGRAM_COUNTS_100(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
 325     name, sample, 1, 100, 50)
 326
 327 #define UMA_HISTOGRAM_COUNTS_10000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
 328     name, sample, 1, 10000, 50)
 329
 330 #define UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \
 331     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
 332         base::Histogram::FactoryGet(name, min, max, bucket_count, \
 333             base::HistogramBase::kUmaTargetedHistogramFlag))
 334
 335 #define UMA_HISTOGRAM_MEMORY_KB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
 336     name, sample, 1000, 500000, 50)
 337
 338 #define UMA_HISTOGRAM_MEMORY_MB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
 339     name, sample, 1, 1000, 50)
 340
 341 #define UMA_HISTOGRAM_PERCENTAGE(name, under_one_hundred) \
 342     UMA_HISTOGRAM_ENUMERATION(name, under_one_hundred, 101)
 343
 344 #define UMA_HISTOGRAM_BOOLEAN(name, sample) \
 345     STATIC_HISTOGRAM_POINTER_BLOCK(name, AddBoolean(sample), \
 346         base::BooleanHistogram::FactoryGet(name, \
 347             base::HistogramBase::kUmaTargetedHistogramFlag))
 348
 349 // The samples should always be strictly less than |boundary_value|.  For more
 350 // details, see the comment for the |HISTOGRAM_ENUMERATION| macro, above.
 351 #define UMA_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \
 352     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
 353         base::LinearHistogram::FactoryGet(name, 1, boundary_value, \
 354             boundary_value + 1, base::HistogramBase::kUmaTargetedHistogramFlag))
 355
 356 #define UMA_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \
 357     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \
 358         base::CustomHistogram::FactoryGet(name, custom_ranges, \
 359             base::HistogramBase::kUmaTargetedHistogramFlag))
 360
 361 //------------------------------------------------------------------------------
 362
 363 class BucketRanges;
 364 class SampleVector;
 365
 366 class BooleanHistogram;
 367 class CustomHistogram;
 368 class Histogram;
 369 class LinearHistogram;
 370
 371 class BASE_EXPORT Histogram : public HistogramBase {
 372  public:
 373   // Initialize maximum number of buckets in histograms as 16,384.
 374   static const size_t kBucketCount_MAX;
 375
 376   typedef std::vector<Count> Counts;
 377
 378   //----------------------------------------------------------------------------
 379   // For a valid histogram, input should follow these restrictions:
 380   // minimum > 0 (if a minimum below 1 is specified, it will implicitly be
 381   //              normalized up to 1)
 382   // maximum > minimum
 383   // buckets > 2 [minimum buckets needed: underflow, overflow and the range]
 384   // Additionally,
 385   // buckets <= (maximum - minimum + 2) - this is to ensure that we don't have
 386   // more buckets than the range of numbers; having more buckets than 1 per
 387   // value in the range would be nonsensical.
 388   static HistogramBase* FactoryGet(const std::string& name,
 389                                    Sample minimum,
 390                                    Sample maximum,
 391                                    size_t bucket_count,
 392                                    int32 flags);
 393   static HistogramBase* FactoryTimeGet(const std::string& name,
 394                                        base::TimeDelta minimum,
 395                                        base::TimeDelta maximum,
 396                                        size_t bucket_count,
 397                                        int32 flags);
 398
 399   // Time call for use with DHISTOGRAM*.
 400   // Returns TimeTicks::Now() in debug and TimeTicks() in release build.
 401   static TimeTicks DebugNow();
 402
 403   static void InitializeBucketRanges(Sample minimum,
 404                                      Sample maximum,
 405                                      BucketRanges* ranges);
 406
 407   // This constant if for FindCorruption. Since snapshots of histograms are
 408   // taken asynchronously relative to sampling, and our counting code currently
 409   // does not prevent race conditions, it is pretty likely that we'll catch a
 410   // redundant count that doesn't match the sample count.  We allow for a
 411   // certain amount of slop before flagging this as an inconsistency. Even with
 412   // an inconsistency, we'll snapshot it again (for UMA in about a half hour),
 413   // so we'll eventually get the data, if it was not the result of a corruption.
 414   static const int kCommonRaceBasedCountMismatch;
 415
 416   // Check to see if bucket ranges, counts and tallies in the snapshot are
 417   // consistent with the bucket ranges and checksums in our histogram.  This can
 418   // produce a false-alarm if a race occurred in the reading of the data during
 419   // a SnapShot process, but should otherwise be false at all times (unless we
 420   // have memory over-writes, or DRAM failures).
 421   virtual int FindCorruption(const HistogramSamples& samples) const OVERRIDE;
 422
 423   //----------------------------------------------------------------------------
 424   // Accessors for factory constuction, serialization and testing.
 425   //----------------------------------------------------------------------------
 426   Sample declared_min() const { return declared_min_; }
 427   Sample declared_max() const { return declared_max_; }
 428   virtual Sample ranges(size_t i) const;
 429   virtual size_t bucket_count() const;
 430   const BucketRanges* bucket_ranges() const { return bucket_ranges_; }
 431
 432   // This function validates histogram construction arguments. It returns false
 433   // if some of the arguments are totally bad.
 434   // Note. Currently it allow some bad input, e.g. 0 as minimum, but silently
 435   // converts it to good input: 1.
 436   // TODO(kaiwang): Be more restrict and return false for any bad input, and
 437   // make this a readonly validating function.
 438   static bool InspectConstructionArguments(const std::string& name,
 439                                            Sample* minimum,
 440                                            Sample* maximum,
 441                                            size_t* bucket_count);
 442
 443   // HistogramBase implementation:
 444   virtual HistogramType GetHistogramType() const OVERRIDE;
 445   virtual bool HasConstructionArguments(
 446       Sample expected_minimum,
 447       Sample expected_maximum,
 448       size_t expected_bucket_count) const OVERRIDE;
 449   virtual void Add(Sample value) OVERRIDE;
 450   virtual scoped_ptr<HistogramSamples> SnapshotSamples() const OVERRIDE;
 451   virtual void AddSamples(const HistogramSamples& samples) OVERRIDE;
 452   virtual bool AddSamplesFromPickle(PickleIterator* iter) OVERRIDE;
 453   virtual void WriteHTMLGraph(std::string* output) const OVERRIDE;
 454   virtual void WriteAscii(std::string* output) const OVERRIDE;
 455
 456  protected:
 457   // |ranges| should contain the underflow and overflow buckets. See top
 458   // comments for example.
 459   Histogram(const std::string& name,
 460             Sample minimum,
 461             Sample maximum,
 462             const BucketRanges* ranges);
 463
 464   virtual ~Histogram();
 465
 466   // HistogramBase implementation:
 467   virtual bool SerializeInfoImpl(Pickle* pickle) const OVERRIDE;
 468
 469   // Method to override to skip the display of the i'th bucket if it's empty.
 470   virtual bool PrintEmptyBucket(size_t index) const;
 471
 472   // Get normalized size, relative to the ranges(i).
 473   virtual double GetBucketSize(Count current, size_t i) const;
 474
 475   // Return a string description of what goes in a given bucket.
 476   // Most commonly this is the numeric value, but in derived classes it may
 477   // be a name (or string description) given to the bucket.
 478   virtual const std::string GetAsciiBucketRange(size_t it) const;
 479
 480  private:
 481   // Allow tests to corrupt our innards for testing purposes.
 482   FRIEND_TEST_ALL_PREFIXES(HistogramTest, BoundsTest);
 483   FRIEND_TEST_ALL_PREFIXES(HistogramTest, BucketPlacementTest);
 484   FRIEND_TEST_ALL_PREFIXES(HistogramTest, CorruptBucketBounds);
 485   FRIEND_TEST_ALL_PREFIXES(HistogramTest, CorruptSampleCounts);
 486   FRIEND_TEST_ALL_PREFIXES(HistogramTest, NameMatchTest);
 487
 488   friend class StatisticsRecorder;  // To allow it to delete duplicates.
 489   friend class StatisticsRecorderTest;
 490
 491   friend BASE_EXPORT_PRIVATE HistogramBase* DeserializeHistogramInfo(
 492       PickleIterator* iter);
 493   static HistogramBase* DeserializeInfoImpl(PickleIterator* iter);
 494
 495   // Implementation of SnapshotSamples function.
 496   scoped_ptr<SampleVector> SnapshotSampleVector() const;
 497
 498   //----------------------------------------------------------------------------
 499   // Helpers for emitting Ascii graphic.  Each method appends data to output.
 500
 501   void WriteAsciiImpl(bool graph_it,
 502                       const std::string& newline,
 503                       std::string* output) const;
 504
 505   // Find out how large (graphically) the largest bucket will appear to be.
 506   double GetPeakBucketSize(const SampleVector& samples) const;
 507
 508   // Write a common header message describing this histogram.
 509   void WriteAsciiHeader(const SampleVector& samples,
 510                         Count sample_count,
 511                         std::string* output) const;
 512
 513   // Write information about previous, current, and next buckets.
 514   // Information such as cumulative percentage, etc.
 515   void WriteAsciiBucketContext(const int64 past, const Count current,
 516                                const int64 remaining, const size_t i,
 517                                std::string* output) const;
 518
 519   // WriteJSON calls these.
 520   virtual void GetParameters(DictionaryValue* params) const OVERRIDE;
 521
 522   virtual void GetCountAndBucketData(Count* count,
 523                                      int64* sum,
 524                                      ListValue* buckets) const OVERRIDE;
 525
 526   // Does not own this object. Should get from StatisticsRecorder.
 527   const BucketRanges* bucket_ranges_;
 528
 529   Sample declared_min_;  // Less than this goes into the first bucket.
 530   Sample declared_max_;  // Over this goes into the last bucket.
 531
 532   // Finally, provide the state that changes with the addition of each new
 533   // sample.
 534   scoped_ptr<SampleVector> samples_;
 535
 536   DISALLOW_COPY_AND_ASSIGN(Histogram);
 537 };
 538
 539 //------------------------------------------------------------------------------
 540
 541 // LinearHistogram is a more traditional histogram, with evenly spaced
 542 // buckets.
 543 class BASE_EXPORT LinearHistogram : public Histogram {
 544  public:
 545   virtual ~LinearHistogram();
 546
 547   /* minimum should start from 1. 0 is as minimum is invalid. 0 is an implicit
 548      default underflow bucket. */
 549   static HistogramBase* FactoryGet(const std::string& name,
 550                                    Sample minimum,
 551                                    Sample maximum,
 552                                    size_t bucket_count,
 553                                    int32 flags);
 554   static HistogramBase* FactoryTimeGet(const std::string& name,
 555                                        TimeDelta minimum,
 556                                        TimeDelta maximum,
 557                                        size_t bucket_count,
 558                                        int32 flags);
 559
 560   struct DescriptionPair {
 561     Sample sample;
 562     const char* description;  // Null means end of a list of pairs.
 563   };
 564
 565   // Create a LinearHistogram and store a list of number/text values for use in
 566   // writing the histogram graph.
 567   // |descriptions| can be NULL, which means no special descriptions to set. If
 568   // it's not NULL, the last element in the array must has a NULL in its
 569   // "description" field.
 570   static HistogramBase* FactoryGetWithRangeDescription(
 571       const std::string& name,
 572       Sample minimum,
 573       Sample maximum,
 574       size_t bucket_count,
 575       int32 flags,
 576       const DescriptionPair descriptions[]);
 577
 578   static void InitializeBucketRanges(Sample minimum,
 579                                      Sample maximum,
 580                                      BucketRanges* ranges);
 581
 582   // Overridden from Histogram:
 583   virtual HistogramType GetHistogramType() const OVERRIDE;
 584
 585  protected:
 586   LinearHistogram(const std::string& name,
 587                   Sample minimum,
 588                   Sample maximum,
 589                   const BucketRanges* ranges);
 590
 591   virtual double GetBucketSize(Count current, size_t i) const OVERRIDE;
 592
 593   // If we have a description for a bucket, then return that.  Otherwise
 594   // let parent class provide a (numeric) description.
 595   virtual const std::string GetAsciiBucketRange(size_t i) const OVERRIDE;
 596
 597   // Skip printing of name for numeric range if we have a name (and if this is
 598   // an empty bucket).
 599   virtual bool PrintEmptyBucket(size_t index) const OVERRIDE;
 600
 601  private:
 602   friend BASE_EXPORT_PRIVATE HistogramBase* DeserializeHistogramInfo(
 603       PickleIterator* iter);
 604   static HistogramBase* DeserializeInfoImpl(PickleIterator* iter);
 605
 606   // For some ranges, we store a printable description of a bucket range.
 607   // If there is no desciption, then GetAsciiBucketRange() uses parent class
 608   // to provide a description.
 609   typedef std::map<Sample, std::string> BucketDescriptionMap;
 610   BucketDescriptionMap bucket_description_;
 611
 612   DISALLOW_COPY_AND_ASSIGN(LinearHistogram);
 613 };
 614
 615 //------------------------------------------------------------------------------
 616
 617 // BooleanHistogram is a histogram for booleans.
 618 class BASE_EXPORT BooleanHistogram : public LinearHistogram {
 619  public:
 620   static HistogramBase* FactoryGet(const std::string& name, int32 flags);
 621
 622   virtual HistogramType GetHistogramType() const OVERRIDE;
 623
 624  private:
 625   BooleanHistogram(const std::string& name, const BucketRanges* ranges);
 626
 627   friend BASE_EXPORT_PRIVATE HistogramBase* DeserializeHistogramInfo(
 628       PickleIterator* iter);
 629   static HistogramBase* DeserializeInfoImpl(PickleIterator* iter);
 630
 631   DISALLOW_COPY_AND_ASSIGN(BooleanHistogram);
 632 };
 633
 634 //------------------------------------------------------------------------------
 635
 636 // CustomHistogram is a histogram for a set of custom integers.
 637 class BASE_EXPORT CustomHistogram : public Histogram {
 638  public:
 639   // |custom_ranges| contains a vector of limits on ranges. Each limit should be
 640   // > 0 and < kSampleType_MAX. (Currently 0 is still accepted for backward
 641   // compatibility). The limits can be unordered or contain duplication, but
 642   // client should not depend on this.
 643   static HistogramBase* FactoryGet(const std::string& name,
 644                                    const std::vector<Sample>& custom_ranges,
 645                                    int32 flags);
 646
 647   // Overridden from Histogram:
 648   virtual HistogramType GetHistogramType() const OVERRIDE;
 649
 650   // Helper method for transforming an array of valid enumeration values
 651   // to the std::vector<int> expected by HISTOGRAM_CUSTOM_ENUMERATION.
 652   // This function ensures that a guard bucket exists right after any
 653   // valid sample value (unless the next higher sample is also a valid value),
 654   // so that invalid samples never fall into the same bucket as valid samples.
 655   // TODO(kaiwang): Change name to ArrayToCustomEnumRanges.
 656   static std::vector<Sample> ArrayToCustomRanges(const Sample* values,
 657                                                  size_t num_values);
 658  protected:
 659   CustomHistogram(const std::string& name,
 660                   const BucketRanges* ranges);
 661
 662   // HistogramBase implementation:
 663   virtual bool SerializeInfoImpl(Pickle* pickle) const OVERRIDE;
 664
 665   virtual double GetBucketSize(Count current, size_t i) const OVERRIDE;
 666
 667  private:
 668   friend BASE_EXPORT_PRIVATE HistogramBase* DeserializeHistogramInfo(
 669       PickleIterator* iter);
 670   static HistogramBase* DeserializeInfoImpl(PickleIterator* iter);
 671
 672   static bool ValidateCustomRanges(const std::vector<Sample>& custom_ranges);
 673   static BucketRanges* CreateBucketRangesFromCustomRanges(
 674       const std::vector<Sample>& custom_ranges);
 675
 676   DISALLOW_COPY_AND_ASSIGN(CustomHistogram);
 677 };
 678
 679 }  // namespace base
 680
 681 #endif  // BASE_METRICS_HISTOGRAM_H_