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 minimal 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 // initialization 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 histogram. 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 construction, serialization and testing. 425 //---------------------------------------------------------------------------- declared_min()426 Sample declared_min() const { return declared_min_; } declared_max()427 Sample declared_max() const { return declared_max_; } 428 virtual Sample ranges(size_t i) const; 429 virtual size_t bucket_count() const; bucket_ranges()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 description, 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_ 682