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 82class Pickle; 83class PickleIterator; 84 85namespace base { 86 87class 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// LOCAL_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 if (DCHECK_IS_ON) \ 159 histogram_pointer->CheckName(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 LOCAL_HISTOGRAM_TIMES(name, sample) LOCAL_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 LOCAL_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 LOCAL_HISTOGRAM_COUNTS(name, sample) LOCAL_HISTOGRAM_CUSTOM_COUNTS( \ 180 name, sample, 1, 1000000, 50) 181 182#define LOCAL_HISTOGRAM_COUNTS_100(name, sample) \ 183 LOCAL_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1, 100, 50) 184 185#define LOCAL_HISTOGRAM_COUNTS_10000(name, sample) \ 186 LOCAL_HISTOGRAM_CUSTOM_COUNTS(name, sample, 1, 10000, 50) 187 188#define LOCAL_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// This is a helper macro used by other macros and shouldn't be used directly. 194#define HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary, flag) \ 195 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 196 base::LinearHistogram::FactoryGet(name, 1, boundary, boundary + 1, \ 197 flag)) 198 199#define LOCAL_HISTOGRAM_PERCENTAGE(name, under_one_hundred) \ 200 LOCAL_HISTOGRAM_ENUMERATION(name, under_one_hundred, 101) 201 202#define LOCAL_HISTOGRAM_BOOLEAN(name, sample) \ 203 STATIC_HISTOGRAM_POINTER_BLOCK(name, AddBoolean(sample), \ 204 base::BooleanHistogram::FactoryGet(name, base::Histogram::kNoFlags)) 205 206// Support histograming of an enumerated value. The samples should always be 207// strictly less than |boundary_value| -- this prevents you from running into 208// problems down the line if you add additional buckets to the histogram. Note 209// also that, despite explicitly setting the minimum bucket value to |1| below, 210// it is fine for enumerated histograms to be 0-indexed -- this is because 211// enumerated histograms should never have underflow. 212#define LOCAL_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \ 213 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 214 base::LinearHistogram::FactoryGet(name, 1, boundary_value, \ 215 boundary_value + 1, base::HistogramBase::kNoFlags)) 216 217// Support histograming of an enumerated value. Samples should be one of the 218// std::vector<int> list provided via |custom_ranges|. See comments above 219// CustomRanges::FactoryGet about the requirement of |custom_ranges|. 220// You can use the helper function CustomHistogram::ArrayToCustomRanges to 221// transform a C-style array of valid sample values to a std::vector<int>. 222#define LOCAL_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \ 223 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 224 base::CustomHistogram::FactoryGet(name, custom_ranges, \ 225 base::HistogramBase::kNoFlags)) 226 227#define LOCAL_HISTOGRAM_MEMORY_KB(name, sample) LOCAL_HISTOGRAM_CUSTOM_COUNTS( \ 228 name, sample, 1000, 500000, 50) 229 230//------------------------------------------------------------------------------ 231// The following macros provide typical usage scenarios for callers that wish 232// to record histogram data, and have the data submitted/uploaded via UMA. 233// Not all systems support such UMA, but if they do, the following macros 234// should work with the service. 235 236#define UMA_HISTOGRAM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ 237 name, sample, base::TimeDelta::FromMilliseconds(1), \ 238 base::TimeDelta::FromSeconds(10), 50) 239 240#define UMA_HISTOGRAM_MEDIUM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ 241 name, sample, base::TimeDelta::FromMilliseconds(10), \ 242 base::TimeDelta::FromMinutes(3), 50) 243 244// Use this macro when times can routinely be much longer than 10 seconds. 245#define UMA_HISTOGRAM_LONG_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ 246 name, sample, base::TimeDelta::FromMilliseconds(1), \ 247 base::TimeDelta::FromHours(1), 50) 248 249// Use this macro when times can routinely be much longer than 10 seconds and 250// you want 100 buckets. 251#define UMA_HISTOGRAM_LONG_TIMES_100(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ 252 name, sample, base::TimeDelta::FromMilliseconds(1), \ 253 base::TimeDelta::FromHours(1), 100) 254 255#define UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \ 256 STATIC_HISTOGRAM_POINTER_BLOCK(name, AddTime(sample), \ 257 base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \ 258 base::HistogramBase::kUmaTargetedHistogramFlag)) 259 260#define UMA_HISTOGRAM_COUNTS(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 261 name, sample, 1, 1000000, 50) 262 263#define UMA_HISTOGRAM_COUNTS_100(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 264 name, sample, 1, 100, 50) 265 266#define UMA_HISTOGRAM_COUNTS_10000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 267 name, sample, 1, 10000, 50) 268 269#define UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \ 270 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 271 base::Histogram::FactoryGet(name, min, max, bucket_count, \ 272 base::HistogramBase::kUmaTargetedHistogramFlag)) 273 274#define UMA_HISTOGRAM_MEMORY_KB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 275 name, sample, 1000, 500000, 50) 276 277#define UMA_HISTOGRAM_MEMORY_MB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ 278 name, sample, 1, 1000, 50) 279 280#define UMA_HISTOGRAM_PERCENTAGE(name, under_one_hundred) \ 281 UMA_HISTOGRAM_ENUMERATION(name, under_one_hundred, 101) 282 283#define UMA_HISTOGRAM_BOOLEAN(name, sample) \ 284 STATIC_HISTOGRAM_POINTER_BLOCK(name, AddBoolean(sample), \ 285 base::BooleanHistogram::FactoryGet(name, \ 286 base::HistogramBase::kUmaTargetedHistogramFlag)) 287 288// The samples should always be strictly less than |boundary_value|. For more 289// details, see the comment for the |HISTOGRAM_ENUMERATION| macro, above. 290#define UMA_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \ 291 HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary_value, \ 292 base::HistogramBase::kUmaTargetedHistogramFlag) 293 294// Similar to UMA_HISTOGRAM_ENUMERATION, but used for recording stability 295// histograms. Use this if recording a histogram that should be part of the 296// initial stability log. 297#define UMA_STABILITY_HISTOGRAM_ENUMERATION(name, sample, boundary_value) \ 298 HISTOGRAM_ENUMERATION_WITH_FLAG(name, sample, boundary_value, \ 299 base::HistogramBase::kUmaStabilityHistogramFlag) 300 301#define UMA_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \ 302 STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample), \ 303 base::CustomHistogram::FactoryGet(name, custom_ranges, \ 304 base::HistogramBase::kUmaTargetedHistogramFlag)) 305 306//------------------------------------------------------------------------------ 307 308class BucketRanges; 309class SampleVector; 310 311class BooleanHistogram; 312class CustomHistogram; 313class Histogram; 314class LinearHistogram; 315 316class BASE_EXPORT Histogram : public HistogramBase { 317 public: 318 // Initialize maximum number of buckets in histograms as 16,384. 319 static const size_t kBucketCount_MAX; 320 321 typedef std::vector<Count> Counts; 322 323 //---------------------------------------------------------------------------- 324 // For a valid histogram, input should follow these restrictions: 325 // minimum > 0 (if a minimum below 1 is specified, it will implicitly be 326 // normalized up to 1) 327 // maximum > minimum 328 // buckets > 2 [minimum buckets needed: underflow, overflow and the range] 329 // Additionally, 330 // buckets <= (maximum - minimum + 2) - this is to ensure that we don't have 331 // more buckets than the range of numbers; having more buckets than 1 per 332 // value in the range would be nonsensical. 333 static HistogramBase* FactoryGet(const std::string& name, 334 Sample minimum, 335 Sample maximum, 336 size_t bucket_count, 337 int32 flags); 338 static HistogramBase* FactoryTimeGet(const std::string& name, 339 base::TimeDelta minimum, 340 base::TimeDelta maximum, 341 size_t bucket_count, 342 int32 flags); 343 344 static void InitializeBucketRanges(Sample minimum, 345 Sample maximum, 346 BucketRanges* ranges); 347 348 // This constant if for FindCorruption. Since snapshots of histograms are 349 // taken asynchronously relative to sampling, and our counting code currently 350 // does not prevent race conditions, it is pretty likely that we'll catch a 351 // redundant count that doesn't match the sample count. We allow for a 352 // certain amount of slop before flagging this as an inconsistency. Even with 353 // an inconsistency, we'll snapshot it again (for UMA in about a half hour), 354 // so we'll eventually get the data, if it was not the result of a corruption. 355 static const int kCommonRaceBasedCountMismatch; 356 357 // Check to see if bucket ranges, counts and tallies in the snapshot are 358 // consistent with the bucket ranges and checksums in our histogram. This can 359 // produce a false-alarm if a race occurred in the reading of the data during 360 // a SnapShot process, but should otherwise be false at all times (unless we 361 // have memory over-writes, or DRAM failures). 362 virtual int FindCorruption(const HistogramSamples& samples) const OVERRIDE; 363 364 //---------------------------------------------------------------------------- 365 // Accessors for factory construction, serialization and testing. 366 //---------------------------------------------------------------------------- 367 Sample declared_min() const { return declared_min_; } 368 Sample declared_max() const { return declared_max_; } 369 virtual Sample ranges(size_t i) const; 370 virtual size_t bucket_count() const; 371 const BucketRanges* bucket_ranges() const { return bucket_ranges_; } 372 373 // This function validates histogram construction arguments. It returns false 374 // if some of the arguments are totally bad. 375 // Note. Currently it allow some bad input, e.g. 0 as minimum, but silently 376 // converts it to good input: 1. 377 // TODO(kaiwang): Be more restrict and return false for any bad input, and 378 // make this a readonly validating function. 379 static bool InspectConstructionArguments(const std::string& name, 380 Sample* minimum, 381 Sample* maximum, 382 size_t* bucket_count); 383 384 // HistogramBase implementation: 385 virtual HistogramType GetHistogramType() const OVERRIDE; 386 virtual bool HasConstructionArguments( 387 Sample expected_minimum, 388 Sample expected_maximum, 389 size_t expected_bucket_count) const OVERRIDE; 390 virtual void Add(Sample value) OVERRIDE; 391 virtual scoped_ptr<HistogramSamples> SnapshotSamples() const OVERRIDE; 392 virtual void AddSamples(const HistogramSamples& samples) OVERRIDE; 393 virtual bool AddSamplesFromPickle(PickleIterator* iter) OVERRIDE; 394 virtual void WriteHTMLGraph(std::string* output) const OVERRIDE; 395 virtual void WriteAscii(std::string* output) const OVERRIDE; 396 397 protected: 398 // |ranges| should contain the underflow and overflow buckets. See top 399 // comments for example. 400 Histogram(const std::string& name, 401 Sample minimum, 402 Sample maximum, 403 const BucketRanges* ranges); 404 405 virtual ~Histogram(); 406 407 // HistogramBase implementation: 408 virtual bool SerializeInfoImpl(Pickle* pickle) const OVERRIDE; 409 410 // Method to override to skip the display of the i'th bucket if it's empty. 411 virtual bool PrintEmptyBucket(size_t index) const; 412 413 // Get normalized size, relative to the ranges(i). 414 virtual double GetBucketSize(Count current, size_t i) const; 415 416 // Return a string description of what goes in a given bucket. 417 // Most commonly this is the numeric value, but in derived classes it may 418 // be a name (or string description) given to the bucket. 419 virtual const std::string GetAsciiBucketRange(size_t it) const; 420 421 private: 422 // Allow tests to corrupt our innards for testing purposes. 423 FRIEND_TEST_ALL_PREFIXES(HistogramTest, BoundsTest); 424 FRIEND_TEST_ALL_PREFIXES(HistogramTest, BucketPlacementTest); 425 FRIEND_TEST_ALL_PREFIXES(HistogramTest, CorruptBucketBounds); 426 FRIEND_TEST_ALL_PREFIXES(HistogramTest, CorruptSampleCounts); 427 FRIEND_TEST_ALL_PREFIXES(HistogramTest, NameMatchTest); 428 429 friend class StatisticsRecorder; // To allow it to delete duplicates. 430 friend class StatisticsRecorderTest; 431 432 friend BASE_EXPORT_PRIVATE HistogramBase* DeserializeHistogramInfo( 433 PickleIterator* iter); 434 static HistogramBase* DeserializeInfoImpl(PickleIterator* iter); 435 436 // Implementation of SnapshotSamples function. 437 scoped_ptr<SampleVector> SnapshotSampleVector() const; 438 439 //---------------------------------------------------------------------------- 440 // Helpers for emitting Ascii graphic. Each method appends data to output. 441 442 void WriteAsciiImpl(bool graph_it, 443 const std::string& newline, 444 std::string* output) const; 445 446 // Find out how large (graphically) the largest bucket will appear to be. 447 double GetPeakBucketSize(const SampleVector& samples) const; 448 449 // Write a common header message describing this histogram. 450 void WriteAsciiHeader(const SampleVector& samples, 451 Count sample_count, 452 std::string* output) const; 453 454 // Write information about previous, current, and next buckets. 455 // Information such as cumulative percentage, etc. 456 void WriteAsciiBucketContext(const int64 past, const Count current, 457 const int64 remaining, const size_t i, 458 std::string* output) const; 459 460 // WriteJSON calls these. 461 virtual void GetParameters(DictionaryValue* params) const OVERRIDE; 462 463 virtual void GetCountAndBucketData(Count* count, 464 int64* sum, 465 ListValue* buckets) const OVERRIDE; 466 467 // Does not own this object. Should get from StatisticsRecorder. 468 const BucketRanges* bucket_ranges_; 469 470 Sample declared_min_; // Less than this goes into the first bucket. 471 Sample declared_max_; // Over this goes into the last bucket. 472 473 // Finally, provide the state that changes with the addition of each new 474 // sample. 475 scoped_ptr<SampleVector> samples_; 476 477 DISALLOW_COPY_AND_ASSIGN(Histogram); 478}; 479 480//------------------------------------------------------------------------------ 481 482// LinearHistogram is a more traditional histogram, with evenly spaced 483// buckets. 484class BASE_EXPORT LinearHistogram : public Histogram { 485 public: 486 virtual ~LinearHistogram(); 487 488 /* minimum should start from 1. 0 is as minimum is invalid. 0 is an implicit 489 default underflow bucket. */ 490 static HistogramBase* FactoryGet(const std::string& name, 491 Sample minimum, 492 Sample maximum, 493 size_t bucket_count, 494 int32 flags); 495 static HistogramBase* FactoryTimeGet(const std::string& name, 496 TimeDelta minimum, 497 TimeDelta maximum, 498 size_t bucket_count, 499 int32 flags); 500 501 struct DescriptionPair { 502 Sample sample; 503 const char* description; // Null means end of a list of pairs. 504 }; 505 506 // Create a LinearHistogram and store a list of number/text values for use in 507 // writing the histogram graph. 508 // |descriptions| can be NULL, which means no special descriptions to set. If 509 // it's not NULL, the last element in the array must has a NULL in its 510 // "description" field. 511 static HistogramBase* FactoryGetWithRangeDescription( 512 const std::string& name, 513 Sample minimum, 514 Sample maximum, 515 size_t bucket_count, 516 int32 flags, 517 const DescriptionPair descriptions[]); 518 519 static void InitializeBucketRanges(Sample minimum, 520 Sample maximum, 521 BucketRanges* ranges); 522 523 // Overridden from Histogram: 524 virtual HistogramType GetHistogramType() const OVERRIDE; 525 526 protected: 527 LinearHistogram(const std::string& name, 528 Sample minimum, 529 Sample maximum, 530 const BucketRanges* ranges); 531 532 virtual double GetBucketSize(Count current, size_t i) const OVERRIDE; 533 534 // If we have a description for a bucket, then return that. Otherwise 535 // let parent class provide a (numeric) description. 536 virtual const std::string GetAsciiBucketRange(size_t i) const OVERRIDE; 537 538 // Skip printing of name for numeric range if we have a name (and if this is 539 // an empty bucket). 540 virtual bool PrintEmptyBucket(size_t index) const OVERRIDE; 541 542 private: 543 friend BASE_EXPORT_PRIVATE HistogramBase* DeserializeHistogramInfo( 544 PickleIterator* iter); 545 static HistogramBase* DeserializeInfoImpl(PickleIterator* iter); 546 547 // For some ranges, we store a printable description of a bucket range. 548 // If there is no description, then GetAsciiBucketRange() uses parent class 549 // to provide a description. 550 typedef std::map<Sample, std::string> BucketDescriptionMap; 551 BucketDescriptionMap bucket_description_; 552 553 DISALLOW_COPY_AND_ASSIGN(LinearHistogram); 554}; 555 556//------------------------------------------------------------------------------ 557 558// BooleanHistogram is a histogram for booleans. 559class BASE_EXPORT BooleanHistogram : public LinearHistogram { 560 public: 561 static HistogramBase* FactoryGet(const std::string& name, int32 flags); 562 563 virtual HistogramType GetHistogramType() const OVERRIDE; 564 565 private: 566 BooleanHistogram(const std::string& name, const BucketRanges* ranges); 567 568 friend BASE_EXPORT_PRIVATE HistogramBase* DeserializeHistogramInfo( 569 PickleIterator* iter); 570 static HistogramBase* DeserializeInfoImpl(PickleIterator* iter); 571 572 DISALLOW_COPY_AND_ASSIGN(BooleanHistogram); 573}; 574 575//------------------------------------------------------------------------------ 576 577// CustomHistogram is a histogram for a set of custom integers. 578class BASE_EXPORT CustomHistogram : public Histogram { 579 public: 580 // |custom_ranges| contains a vector of limits on ranges. Each limit should be 581 // > 0 and < kSampleType_MAX. (Currently 0 is still accepted for backward 582 // compatibility). The limits can be unordered or contain duplication, but 583 // client should not depend on this. 584 static HistogramBase* FactoryGet(const std::string& name, 585 const std::vector<Sample>& custom_ranges, 586 int32 flags); 587 588 // Overridden from Histogram: 589 virtual HistogramType GetHistogramType() const OVERRIDE; 590 591 // Helper method for transforming an array of valid enumeration values 592 // to the std::vector<int> expected by UMA_HISTOGRAM_CUSTOM_ENUMERATION. 593 // This function ensures that a guard bucket exists right after any 594 // valid sample value (unless the next higher sample is also a valid value), 595 // so that invalid samples never fall into the same bucket as valid samples. 596 // TODO(kaiwang): Change name to ArrayToCustomEnumRanges. 597 static std::vector<Sample> ArrayToCustomRanges(const Sample* values, 598 size_t num_values); 599 protected: 600 CustomHistogram(const std::string& name, 601 const BucketRanges* ranges); 602 603 // HistogramBase implementation: 604 virtual bool SerializeInfoImpl(Pickle* pickle) const OVERRIDE; 605 606 virtual double GetBucketSize(Count current, size_t i) const OVERRIDE; 607 608 private: 609 friend BASE_EXPORT_PRIVATE HistogramBase* DeserializeHistogramInfo( 610 PickleIterator* iter); 611 static HistogramBase* DeserializeInfoImpl(PickleIterator* iter); 612 613 static bool ValidateCustomRanges(const std::vector<Sample>& custom_ranges); 614 static BucketRanges* CreateBucketRangesFromCustomRanges( 615 const std::vector<Sample>& custom_ranges); 616 617 DISALLOW_COPY_AND_ASSIGN(CustomHistogram); 618}; 619 620} // namespace base 621 622#endif // BASE_METRICS_HISTOGRAM_H_ 623