michael@0: // Copyright (c) 2011 The Chromium Authors. All rights reserved. michael@0: // Use of this source code is governed by a BSD-style license that can be michael@0: // found in the LICENSE file. michael@0: michael@0: // Histogram is an object that aggregates statistics, and can summarize them in michael@0: // various forms, including ASCII graphical, HTML, and numerically (as a michael@0: // vector of numbers corresponding to each of the aggregating buckets). michael@0: michael@0: // It supports calls to accumulate either time intervals (which are processed michael@0: // as integral number of milliseconds), or arbitrary integral units. michael@0: michael@0: // The default layout of buckets is exponential. For example, buckets might michael@0: // contain (sequentially) the count of values in the following intervals: michael@0: // [0,1), [1,2), [2,4), [4,8), [8,16), [16,32), [32,64), [64,infinity) michael@0: // That bucket allocation would actually result from construction of a histogram michael@0: // for values between 1 and 64, with 8 buckets, such as: michael@0: // Histogram count(L"some name", 1, 64, 8); michael@0: // Note that the underflow bucket [0,1) and the overflow bucket [64,infinity) michael@0: // are not counted by the constructor in the user supplied "bucket_count" michael@0: // argument. michael@0: // The above example has an exponential ratio of 2 (doubling the bucket width michael@0: // in each consecutive bucket. The Histogram class automatically calculates michael@0: // the smallest ratio that it can use to construct the number of buckets michael@0: // selected in the constructor. An another example, if you had 50 buckets, michael@0: // and millisecond time values from 1 to 10000, then the ratio between michael@0: // consecutive bucket widths will be approximately somewhere around the 50th michael@0: // root of 10000. This approach provides very fine grain (narrow) buckets michael@0: // at the low end of the histogram scale, but allows the histogram to cover a michael@0: // gigantic range with the addition of very few buckets. michael@0: michael@0: // Histograms use a pattern involving a function static variable, that is a michael@0: // pointer to a histogram. This static is explicitly initialized on any thread michael@0: // that detects a uninitialized (NULL) pointer. The potentially racy michael@0: // initialization is not a problem as it is always set to point to the same michael@0: // value (i.e., the FactoryGet always returns the same value). FactoryGet michael@0: // is also completely thread safe, which results in a completely thread safe, michael@0: // and relatively fast, set of counters. To avoid races at shutdown, the static michael@0: // pointer is NOT deleted, and we leak the histograms at process termination. michael@0: michael@0: #ifndef BASE_METRICS_HISTOGRAM_H_ michael@0: #define BASE_METRICS_HISTOGRAM_H_ michael@0: #pragma once michael@0: michael@0: #include "mozilla/MemoryReporting.h" michael@0: michael@0: #include michael@0: #include michael@0: #include michael@0: michael@0: #include "base/time.h" michael@0: #include "base/lock.h" michael@0: michael@0: class Pickle; michael@0: michael@0: namespace base { michael@0: //------------------------------------------------------------------------------ michael@0: // Provide easy general purpose histogram in a macro, just like stats counters. michael@0: // The first four macros use 50 buckets. michael@0: michael@0: #define HISTOGRAM_TIMES(name, sample) HISTOGRAM_CUSTOM_TIMES( \ michael@0: name, sample, base::TimeDelta::FromMilliseconds(1), \ michael@0: base::TimeDelta::FromSeconds(10), 50) michael@0: michael@0: #define HISTOGRAM_COUNTS(name, sample) HISTOGRAM_CUSTOM_COUNTS( \ michael@0: name, sample, 1, 1000000, 50) michael@0: michael@0: #define HISTOGRAM_COUNTS_100(name, sample) HISTOGRAM_CUSTOM_COUNTS( \ michael@0: name, sample, 1, 100, 50) michael@0: michael@0: #define HISTOGRAM_COUNTS_10000(name, sample) HISTOGRAM_CUSTOM_COUNTS( \ michael@0: name, sample, 1, 10000, 50) michael@0: michael@0: #define HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::Histogram::FactoryGet(name, min, max, bucket_count, \ michael@0: base::Histogram::kNoFlags); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: counter->Add(sample); \ michael@0: } while (0) michael@0: michael@0: #define HISTOGRAM_PERCENTAGE(name, under_one_hundred) \ michael@0: HISTOGRAM_ENUMERATION(name, under_one_hundred, 101) michael@0: michael@0: // For folks that need real specific times, use this to select a precise range michael@0: // of times you want plotted, and the number of buckets you want used. michael@0: #define HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \ michael@0: base::Histogram::kNoFlags); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: counter->AddTime(sample); \ michael@0: } while (0) michael@0: michael@0: // DO NOT USE THIS. It is being phased out, in favor of HISTOGRAM_CUSTOM_TIMES. michael@0: #define HISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \ michael@0: base::Histogram::kNoFlags); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: if ((sample) < (max)) counter->AddTime(sample); \ michael@0: } while (0) michael@0: michael@0: // Support histograming of an enumerated value. The samples should always be michael@0: // less than boundary_value. michael@0: michael@0: #define HISTOGRAM_ENUMERATION(name, sample, boundary_value) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::LinearHistogram::FactoryGet(name, 1, boundary_value, \ michael@0: boundary_value + 1, base::Histogram::kNoFlags); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: counter->Add(sample); \ michael@0: } while (0) michael@0: michael@0: #define HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::CustomHistogram::FactoryGet(name, custom_ranges, \ michael@0: base::Histogram::kNoFlags); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: counter->Add(sample); \ michael@0: } while (0) michael@0: michael@0: michael@0: //------------------------------------------------------------------------------ michael@0: // Define Debug vs non-debug flavors of macros. michael@0: #ifndef NDEBUG michael@0: michael@0: #define DHISTOGRAM_TIMES(name, sample) HISTOGRAM_TIMES(name, sample) michael@0: #define DHISTOGRAM_COUNTS(name, sample) HISTOGRAM_COUNTS(name, sample) michael@0: #define DHISTOGRAM_PERCENTAGE(name, under_one_hundred) HISTOGRAM_PERCENTAGE(\ michael@0: name, under_one_hundred) michael@0: #define DHISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \ michael@0: HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) michael@0: #define DHISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) \ michael@0: HISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) michael@0: #define DHISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \ michael@0: HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) michael@0: #define DHISTOGRAM_ENUMERATION(name, sample, boundary_value) \ michael@0: HISTOGRAM_ENUMERATION(name, sample, boundary_value) michael@0: #define DHISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \ michael@0: HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) michael@0: michael@0: #else // NDEBUG michael@0: michael@0: #define DHISTOGRAM_TIMES(name, sample) do {} while (0) michael@0: #define DHISTOGRAM_COUNTS(name, sample) do {} while (0) michael@0: #define DHISTOGRAM_PERCENTAGE(name, under_one_hundred) do {} while (0) michael@0: #define DHISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \ michael@0: do {} while (0) michael@0: #define DHISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) \ michael@0: do {} while (0) michael@0: #define DHISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \ michael@0: do {} while (0) michael@0: #define DHISTOGRAM_ENUMERATION(name, sample, boundary_value) do {} while (0) michael@0: #define DHISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \ michael@0: do {} while (0) michael@0: michael@0: #endif // NDEBUG michael@0: michael@0: //------------------------------------------------------------------------------ michael@0: // The following macros provide typical usage scenarios for callers that wish michael@0: // to record histogram data, and have the data submitted/uploaded via UMA. michael@0: // Not all systems support such UMA, but if they do, the following macros michael@0: // should work with the service. michael@0: michael@0: #define UMA_HISTOGRAM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ michael@0: name, sample, base::TimeDelta::FromMilliseconds(1), \ michael@0: base::TimeDelta::FromSeconds(10), 50) michael@0: michael@0: #define UMA_HISTOGRAM_MEDIUM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ michael@0: name, sample, base::TimeDelta::FromMilliseconds(10), \ michael@0: base::TimeDelta::FromMinutes(3), 50) michael@0: michael@0: // Use this macro when times can routinely be much longer than 10 seconds. michael@0: #define UMA_HISTOGRAM_LONG_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \ michael@0: name, sample, base::TimeDelta::FromMilliseconds(1), \ michael@0: base::TimeDelta::FromHours(1), 50) michael@0: michael@0: #define UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \ michael@0: base::Histogram::kUmaTargetedHistogramFlag); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: counter->AddTime(sample); \ michael@0: } while (0) michael@0: michael@0: // DO NOT USE THIS. It is being phased out, in favor of HISTOGRAM_CUSTOM_TIMES. michael@0: #define UMA_HISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \ michael@0: base::Histogram::kUmaTargetedHistogramFlag); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: if ((sample) < (max)) counter->AddTime(sample); \ michael@0: } while (0) michael@0: michael@0: #define UMA_HISTOGRAM_COUNTS(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ michael@0: name, sample, 1, 1000000, 50) michael@0: michael@0: #define UMA_HISTOGRAM_COUNTS_100(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ michael@0: name, sample, 1, 100, 50) michael@0: michael@0: #define UMA_HISTOGRAM_COUNTS_10000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ michael@0: name, sample, 1, 10000, 50) michael@0: michael@0: #define UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::Histogram::FactoryGet(name, min, max, bucket_count, \ michael@0: base::Histogram::kUmaTargetedHistogramFlag); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: counter->Add(sample); \ michael@0: } while (0) michael@0: michael@0: #define UMA_HISTOGRAM_MEMORY_KB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ michael@0: name, sample, 1000, 500000, 50) michael@0: michael@0: #define UMA_HISTOGRAM_MEMORY_MB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \ michael@0: name, sample, 1, 1000, 50) michael@0: michael@0: #define UMA_HISTOGRAM_PERCENTAGE(name, under_one_hundred) \ michael@0: UMA_HISTOGRAM_ENUMERATION(name, under_one_hundred, 101) michael@0: michael@0: #define UMA_HISTOGRAM_BOOLEAN(name, sample) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::BooleanHistogram::FactoryGet(name, \ michael@0: base::Histogram::kUmaTargetedHistogramFlag); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: counter->AddBoolean(sample); \ michael@0: } while (0) michael@0: michael@0: #define UMA_HISTOGRAM_ENUMERATION(name, sample, boundary_value) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::LinearHistogram::FactoryGet(name, 1, boundary_value, \ michael@0: boundary_value + 1, base::Histogram::kUmaTargetedHistogramFlag); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: counter->Add(sample); \ michael@0: } while (0) michael@0: michael@0: #define UMA_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) do { \ michael@0: static base::Histogram* counter(NULL); \ michael@0: if (!counter) \ michael@0: counter = base::CustomHistogram::FactoryGet(name, custom_ranges, \ michael@0: base::Histogram::kUmaTargetedHistogramFlag); \ michael@0: DCHECK_EQ(name, counter->histogram_name()); \ michael@0: counter->Add(sample); \ michael@0: } while (0) michael@0: michael@0: //------------------------------------------------------------------------------ michael@0: michael@0: class BooleanHistogram; michael@0: class CustomHistogram; michael@0: class Histogram; michael@0: class LinearHistogram; michael@0: michael@0: class Histogram { michael@0: public: michael@0: typedef int Sample; // Used for samples (and ranges of samples). michael@0: typedef int Count; // Used to count samples in a bucket. michael@0: static const Sample kSampleType_MAX = INT_MAX; michael@0: // Initialize maximum number of buckets in histograms as 16,384. michael@0: static const size_t kBucketCount_MAX; michael@0: michael@0: typedef std::vector Counts; michael@0: typedef std::vector Ranges; michael@0: michael@0: // These enums are used to facilitate deserialization of renderer histograms michael@0: // into the browser. michael@0: enum ClassType { michael@0: HISTOGRAM, michael@0: LINEAR_HISTOGRAM, michael@0: BOOLEAN_HISTOGRAM, michael@0: FLAG_HISTOGRAM, michael@0: CUSTOM_HISTOGRAM, michael@0: NOT_VALID_IN_RENDERER michael@0: }; michael@0: michael@0: enum BucketLayout { michael@0: EXPONENTIAL, michael@0: LINEAR, michael@0: CUSTOM michael@0: }; michael@0: michael@0: enum Flags { michael@0: kNoFlags = 0, michael@0: kUmaTargetedHistogramFlag = 0x1, // Histogram should be UMA uploaded. michael@0: kExtendedStatisticsFlag = 0x2, // OK to gather extended statistics on histograms. michael@0: michael@0: // Indicate that the histogram was pickled to be sent across an IPC Channel. michael@0: // If we observe this flag on a histogram being aggregated into after IPC, michael@0: // then we are running in a single process mode, and the aggregation should michael@0: // not take place (as we would be aggregating back into the source michael@0: // histogram!). michael@0: kIPCSerializationSourceFlag = 0x10, michael@0: michael@0: kHexRangePrintingFlag = 0x8000 // Fancy bucket-naming supported. michael@0: }; michael@0: michael@0: enum Inconsistencies { michael@0: NO_INCONSISTENCIES = 0x0, michael@0: RANGE_CHECKSUM_ERROR = 0x1, michael@0: BUCKET_ORDER_ERROR = 0x2, michael@0: COUNT_HIGH_ERROR = 0x4, michael@0: COUNT_LOW_ERROR = 0x8, michael@0: michael@0: NEVER_EXCEEDED_VALUE = 0x10 michael@0: }; michael@0: michael@0: struct DescriptionPair { michael@0: Sample sample; michael@0: const char* description; // Null means end of a list of pairs. michael@0: }; michael@0: michael@0: size_t SizeOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf); michael@0: michael@0: //---------------------------------------------------------------------------- michael@0: // Statistic values, developed over the life of the histogram. michael@0: michael@0: class SampleSet { michael@0: public: michael@0: explicit SampleSet(); michael@0: ~SampleSet(); michael@0: michael@0: // Adjust size of counts_ for use with given histogram. michael@0: void Resize(const Histogram& histogram); michael@0: void CheckSize(const Histogram& histogram) const; michael@0: michael@0: // Accessor for histogram to make routine additions. michael@0: void AccumulateWithLinearStats(Sample value, Count count, size_t index); michael@0: // Alternate routine for exponential histograms. michael@0: // computeExpensiveStatistics should be true if we want to compute log sums. michael@0: void AccumulateWithExponentialStats(Sample value, Count count, size_t index, michael@0: bool computeExtendedStatistics); michael@0: michael@0: // Accessor methods. michael@0: Count counts(size_t i) const { return counts_[i]; } michael@0: Count TotalCount() const; michael@0: int64_t sum() const { return sum_; } michael@0: uint64_t sum_squares() const { return sum_squares_; } michael@0: double log_sum() const { return log_sum_; } michael@0: double log_sum_squares() const { return log_sum_squares_; } michael@0: int64_t redundant_count() const { return redundant_count_; } michael@0: size_t size() const { return counts_.size(); } michael@0: michael@0: // Arithmetic manipulation of corresponding elements of the set. michael@0: void Add(const SampleSet& other); michael@0: void Subtract(const SampleSet& other); michael@0: michael@0: bool Serialize(Pickle* pickle) const; michael@0: bool Deserialize(void** iter, const Pickle& pickle); michael@0: michael@0: size_t SizeOfExcludingThis(mozilla::MallocSizeOf aMallocSizeOf); michael@0: michael@0: protected: michael@0: // Actual histogram data is stored in buckets, showing the count of values michael@0: // that fit into each bucket. michael@0: Counts counts_; michael@0: michael@0: // Save simple stats locally. Note that this MIGHT get done in base class michael@0: // without shared memory at some point. michael@0: int64_t sum_; // sum of samples. michael@0: uint64_t sum_squares_; // sum of squares of samples. michael@0: michael@0: // These fields may or may not be updated at the discretion of the michael@0: // histogram. We use the natural log and compute ln(sample+1) so that michael@0: // zeros are handled sanely. michael@0: double log_sum_; // sum of logs of samples. michael@0: double log_sum_squares_; // sum of squares of logs of samples michael@0: michael@0: private: michael@0: void Accumulate(Sample value, Count count, size_t index); michael@0: michael@0: // To help identify memory corruption, we reduntantly save the number of michael@0: // samples we've accumulated into all of our buckets. We can compare this michael@0: // count to the sum of the counts in all buckets, and detect problems. Note michael@0: // that due to races in histogram accumulation (if a histogram is indeed michael@0: // updated on several threads simultaneously), the tallies might mismatch, michael@0: // and also the snapshotting code may asynchronously get a mismatch (though michael@0: // generally either race based mismatch cause is VERY rare). michael@0: int64_t redundant_count_; michael@0: }; michael@0: michael@0: //---------------------------------------------------------------------------- michael@0: // minimum should start from 1. 0 is invalid as a minimum. 0 is an implicit michael@0: // default underflow bucket. michael@0: static Histogram* FactoryGet(const std::string& name, michael@0: Sample minimum, michael@0: Sample maximum, michael@0: size_t bucket_count, michael@0: Flags flags); michael@0: static Histogram* FactoryTimeGet(const std::string& name, michael@0: base::TimeDelta minimum, michael@0: base::TimeDelta maximum, michael@0: size_t bucket_count, michael@0: Flags flags); michael@0: michael@0: void Add(int value); michael@0: void Subtract(int value); michael@0: michael@0: // This method is an interface, used only by BooleanHistogram. michael@0: virtual void AddBoolean(bool value); michael@0: michael@0: // Accept a TimeDelta to increment. michael@0: void AddTime(TimeDelta time) { michael@0: Add(static_cast(time.InMilliseconds())); michael@0: } michael@0: michael@0: virtual void AddSampleSet(const SampleSet& sample); michael@0: michael@0: void Clear(); michael@0: michael@0: // This method is an interface, used only by LinearHistogram. michael@0: virtual void SetRangeDescriptions(const DescriptionPair descriptions[]); michael@0: michael@0: // The following methods provide graphical histogram displays. michael@0: void WriteHTMLGraph(std::string* output) const; michael@0: void WriteAscii(bool graph_it, const std::string& newline, michael@0: std::string* output) const; michael@0: michael@0: // Support generic flagging of Histograms. michael@0: // 0x1 Currently used to mark this histogram to be recorded by UMA.. michael@0: // 0x8000 means print ranges in hex. michael@0: void SetFlags(Flags flags) { flags_ = static_cast (flags_ | flags); } michael@0: void ClearFlags(Flags flags) { flags_ = static_cast(flags_ & ~flags); } michael@0: int flags() const { return flags_; } michael@0: michael@0: // Convenience methods for serializing/deserializing the histograms. michael@0: // Histograms from Renderer process are serialized and sent to the browser. michael@0: // Browser process reconstructs the histogram from the pickled version michael@0: // accumulates the browser-side shadow copy of histograms (that mirror michael@0: // histograms created in the renderer). michael@0: michael@0: // Serialize the given snapshot of a Histogram into a String. Uses michael@0: // Pickle class to flatten the object. michael@0: static std::string SerializeHistogramInfo(const Histogram& histogram, michael@0: const SampleSet& snapshot); michael@0: // The following method accepts a list of pickled histograms and michael@0: // builds a histogram and updates shadow copy of histogram data in the michael@0: // browser process. michael@0: static bool DeserializeHistogramInfo(const std::string& histogram_info); michael@0: michael@0: // Check to see if bucket ranges, counts and tallies in the snapshot are michael@0: // consistent with the bucket ranges and checksums in our histogram. This can michael@0: // produce a false-alarm if a race occurred in the reading of the data during michael@0: // a SnapShot process, but should otherwise be false at all times (unless we michael@0: // have memory over-writes, or DRAM failures). michael@0: virtual Inconsistencies FindCorruption(const SampleSet& snapshot) const; michael@0: michael@0: //---------------------------------------------------------------------------- michael@0: // Accessors for factory constuction, serialization and testing. michael@0: //---------------------------------------------------------------------------- michael@0: virtual ClassType histogram_type() const; michael@0: const std::string& histogram_name() const { return histogram_name_; } michael@0: Sample declared_min() const { return declared_min_; } michael@0: Sample declared_max() const { return declared_max_; } michael@0: virtual Sample ranges(size_t i) const; michael@0: uint32_t range_checksum() const { return range_checksum_; } michael@0: virtual size_t bucket_count() const; michael@0: // Snapshot the current complete set of sample data. michael@0: // Override with atomic/locked snapshot if needed. michael@0: virtual void SnapshotSample(SampleSet* sample) const; michael@0: michael@0: virtual bool HasConstructorArguments(Sample minimum, Sample maximum, michael@0: size_t bucket_count); michael@0: michael@0: virtual bool HasConstructorTimeDeltaArguments(TimeDelta minimum, michael@0: TimeDelta maximum, michael@0: size_t bucket_count); michael@0: // Return true iff the range_checksum_ matches current ranges_ vector. michael@0: bool HasValidRangeChecksum() const; michael@0: michael@0: protected: michael@0: Histogram(const std::string& name, Sample minimum, michael@0: Sample maximum, size_t bucket_count); michael@0: Histogram(const std::string& name, TimeDelta minimum, michael@0: TimeDelta maximum, size_t bucket_count); michael@0: michael@0: virtual ~Histogram(); michael@0: michael@0: // Initialize ranges_ mapping. michael@0: void InitializeBucketRange(); michael@0: michael@0: // Method to override to skip the display of the i'th bucket if it's empty. michael@0: virtual bool PrintEmptyBucket(size_t index) const; michael@0: michael@0: //---------------------------------------------------------------------------- michael@0: // Methods to override to create histogram with different bucket widths. michael@0: //---------------------------------------------------------------------------- michael@0: // Find bucket to increment for sample value. michael@0: virtual size_t BucketIndex(Sample value) const; michael@0: // Get normalized size, relative to the ranges_[i]. michael@0: virtual double GetBucketSize(Count current, size_t i) const; michael@0: michael@0: // Recalculate range_checksum_. michael@0: void ResetRangeChecksum(); michael@0: michael@0: // Return a string description of what goes in a given bucket. michael@0: // Most commonly this is the numeric value, but in derived classes it may michael@0: // be a name (or string description) given to the bucket. michael@0: virtual const std::string GetAsciiBucketRange(size_t it) const; michael@0: michael@0: //---------------------------------------------------------------------------- michael@0: // Methods to override to create thread safe histogram. michael@0: //---------------------------------------------------------------------------- michael@0: // Update all our internal data, including histogram michael@0: virtual void Accumulate(Sample value, Count count, size_t index); michael@0: michael@0: //---------------------------------------------------------------------------- michael@0: // Accessors for derived classes. michael@0: //---------------------------------------------------------------------------- michael@0: void SetBucketRange(size_t i, Sample value); michael@0: michael@0: // Validate that ranges_ was created sensibly (top and bottom range michael@0: // values relate properly to the declared_min_ and declared_max_).. michael@0: bool ValidateBucketRanges() const; michael@0: michael@0: virtual uint32_t CalculateRangeChecksum() const; michael@0: michael@0: // Finally, provide the state that changes with the addition of each new michael@0: // sample. michael@0: SampleSet sample_; michael@0: michael@0: private: michael@0: friend class StatisticsRecorder; // To allow it to delete duplicates. michael@0: michael@0: // Post constructor initialization. michael@0: void Initialize(); michael@0: michael@0: // Checksum function for accumulating range values into a checksum. michael@0: static uint32_t Crc32(uint32_t sum, Sample range); michael@0: michael@0: //---------------------------------------------------------------------------- michael@0: // Helpers for emitting Ascii graphic. Each method appends data to output. michael@0: michael@0: // Find out how large the (graphically) the largest bucket will appear to be. michael@0: double GetPeakBucketSize(const SampleSet& snapshot) const; michael@0: michael@0: // Write a common header message describing this histogram. michael@0: void WriteAsciiHeader(const SampleSet& snapshot, michael@0: Count sample_count, std::string* output) const; michael@0: michael@0: // Write information about previous, current, and next buckets. michael@0: // Information such as cumulative percentage, etc. michael@0: void WriteAsciiBucketContext(const int64_t past, const Count current, michael@0: const int64_t remaining, const size_t i, michael@0: std::string* output) const; michael@0: michael@0: // Write textual description of the bucket contents (relative to histogram). michael@0: // Output is the count in the buckets, as well as the percentage. michael@0: void WriteAsciiBucketValue(Count current, double scaled_sum, michael@0: std::string* output) const; michael@0: michael@0: // Produce actual graph (set of blank vs non blank char's) for a bucket. michael@0: void WriteAsciiBucketGraph(double current_size, double max_size, michael@0: std::string* output) const; michael@0: michael@0: //---------------------------------------------------------------------------- michael@0: // Table for generating Crc32 values. michael@0: static const uint32_t kCrcTable[256]; michael@0: //---------------------------------------------------------------------------- michael@0: // Invariant values set at/near construction time michael@0: michael@0: // ASCII version of original name given to the constructor. All identically michael@0: // named instances will be coalesced cross-project. michael@0: const std::string histogram_name_; michael@0: Sample declared_min_; // Less than this goes into counts_[0] michael@0: Sample declared_max_; // Over this goes into counts_[bucket_count_ - 1]. michael@0: size_t bucket_count_; // Dimension of counts_[]. michael@0: michael@0: // Flag the histogram for recording by UMA via metric_services.h. michael@0: Flags flags_; michael@0: michael@0: // For each index, show the least value that can be stored in the michael@0: // corresponding bucket. We also append one extra element in this array, michael@0: // containing kSampleType_MAX, to make calculations easy. michael@0: // The dimension of ranges_ is bucket_count + 1. michael@0: Ranges ranges_; michael@0: michael@0: // For redundancy, we store a checksum of all the sample ranges when ranges michael@0: // are generated. If ever there is ever a difference, then the histogram must michael@0: // have been corrupted. michael@0: uint32_t range_checksum_; michael@0: michael@0: DISALLOW_COPY_AND_ASSIGN(Histogram); michael@0: }; michael@0: michael@0: //------------------------------------------------------------------------------ michael@0: michael@0: // LinearHistogram is a more traditional histogram, with evenly spaced michael@0: // buckets. michael@0: class LinearHistogram : public Histogram { michael@0: public: michael@0: virtual ~LinearHistogram(); michael@0: michael@0: /* minimum should start from 1. 0 is as minimum is invalid. 0 is an implicit michael@0: default underflow bucket. */ michael@0: static Histogram* FactoryGet(const std::string& name, michael@0: Sample minimum, michael@0: Sample maximum, michael@0: size_t bucket_count, michael@0: Flags flags); michael@0: static Histogram* FactoryTimeGet(const std::string& name, michael@0: TimeDelta minimum, michael@0: TimeDelta maximum, michael@0: size_t bucket_count, michael@0: Flags flags); michael@0: michael@0: // Overridden from Histogram: michael@0: virtual ClassType histogram_type() const; michael@0: michael@0: virtual void Accumulate(Sample value, Count count, size_t index); michael@0: michael@0: // Store a list of number/text values for use in rendering the histogram. michael@0: // The last element in the array has a null in its "description" slot. michael@0: virtual void SetRangeDescriptions(const DescriptionPair descriptions[]); michael@0: michael@0: protected: michael@0: LinearHistogram(const std::string& name, Sample minimum, michael@0: Sample maximum, size_t bucket_count); michael@0: michael@0: LinearHistogram(const std::string& name, TimeDelta minimum, michael@0: TimeDelta maximum, size_t bucket_count); michael@0: michael@0: // Initialize ranges_ mapping. michael@0: void InitializeBucketRange(); michael@0: virtual double GetBucketSize(Count current, size_t i) const; michael@0: michael@0: // If we have a description for a bucket, then return that. Otherwise michael@0: // let parent class provide a (numeric) description. michael@0: virtual const std::string GetAsciiBucketRange(size_t i) const; michael@0: michael@0: // Skip printing of name for numeric range if we have a name (and if this is michael@0: // an empty bucket). michael@0: virtual bool PrintEmptyBucket(size_t index) const; michael@0: michael@0: private: michael@0: // For some ranges, we store a printable description of a bucket range. michael@0: // If there is no desciption, then GetAsciiBucketRange() uses parent class michael@0: // to provide a description. michael@0: typedef std::map BucketDescriptionMap; michael@0: BucketDescriptionMap bucket_description_; michael@0: michael@0: DISALLOW_COPY_AND_ASSIGN(LinearHistogram); michael@0: }; michael@0: michael@0: //------------------------------------------------------------------------------ michael@0: michael@0: // BooleanHistogram is a histogram for booleans. michael@0: class BooleanHistogram : public LinearHistogram { michael@0: public: michael@0: static Histogram* FactoryGet(const std::string& name, Flags flags); michael@0: michael@0: virtual ClassType histogram_type() const; michael@0: michael@0: virtual void AddBoolean(bool value); michael@0: michael@0: virtual void Accumulate(Sample value, Count count, size_t index); michael@0: michael@0: protected: michael@0: explicit BooleanHistogram(const std::string& name); michael@0: michael@0: DISALLOW_COPY_AND_ASSIGN(BooleanHistogram); michael@0: }; michael@0: michael@0: //------------------------------------------------------------------------------ michael@0: michael@0: // FlagHistogram is like boolean histogram, but only allows a single off/on value. michael@0: class FlagHistogram : public BooleanHistogram michael@0: { michael@0: public: michael@0: static Histogram *FactoryGet(const std::string &name, Flags flags); michael@0: michael@0: virtual ClassType histogram_type() const; michael@0: michael@0: virtual void Accumulate(Sample value, Count count, size_t index); michael@0: michael@0: virtual void AddSampleSet(const SampleSet& sample); michael@0: michael@0: private: michael@0: explicit FlagHistogram(const std::string &name); michael@0: bool mSwitched; michael@0: michael@0: DISALLOW_COPY_AND_ASSIGN(FlagHistogram); michael@0: }; michael@0: michael@0: //------------------------------------------------------------------------------ michael@0: michael@0: // CustomHistogram is a histogram for a set of custom integers. michael@0: class CustomHistogram : public Histogram { michael@0: public: michael@0: michael@0: static Histogram* FactoryGet(const std::string& name, michael@0: const std::vector& custom_ranges, michael@0: Flags flags); michael@0: michael@0: // Overridden from Histogram: michael@0: virtual ClassType histogram_type() const; michael@0: michael@0: protected: michael@0: CustomHistogram(const std::string& name, michael@0: const std::vector& custom_ranges); michael@0: michael@0: // Initialize ranges_ mapping. michael@0: void InitializedCustomBucketRange(const std::vector& custom_ranges); michael@0: virtual double GetBucketSize(Count current, size_t i) const; michael@0: michael@0: DISALLOW_COPY_AND_ASSIGN(CustomHistogram); michael@0: }; michael@0: michael@0: //------------------------------------------------------------------------------ michael@0: // StatisticsRecorder handles all histograms in the system. It provides a michael@0: // general place for histograms to register, and supports a global API for michael@0: // accessing (i.e., dumping, or graphing) the data in all the histograms. michael@0: michael@0: class StatisticsRecorder { michael@0: public: michael@0: typedef std::vector Histograms; michael@0: michael@0: StatisticsRecorder(); michael@0: michael@0: ~StatisticsRecorder(); michael@0: michael@0: // Find out if histograms can now be registered into our list. michael@0: static bool IsActive(); michael@0: michael@0: // Register, or add a new histogram to the collection of statistics. If an michael@0: // identically named histogram is already registered, then the argument michael@0: // |histogram| will deleted. The returned value is always the registered michael@0: // histogram (either the argument, or the pre-existing registered histogram). michael@0: static Histogram* RegisterOrDeleteDuplicate(Histogram* histogram); michael@0: michael@0: // Methods for printing histograms. Only histograms which have query as michael@0: // a substring are written to output (an empty string will process all michael@0: // registered histograms). michael@0: static void WriteHTMLGraph(const std::string& query, std::string* output); michael@0: static void WriteGraph(const std::string& query, std::string* output); michael@0: michael@0: // Method for extracting histograms which were marked for use by UMA. michael@0: static void GetHistograms(Histograms* output); michael@0: michael@0: // Find a histogram by name. It matches the exact name. This method is thread michael@0: // safe. If a matching histogram is not found, then the |histogram| is michael@0: // not changed. michael@0: static bool FindHistogram(const std::string& query, Histogram** histogram); michael@0: michael@0: static bool dump_on_exit() { return dump_on_exit_; } michael@0: michael@0: static void set_dump_on_exit(bool enable) { dump_on_exit_ = enable; } michael@0: michael@0: // GetSnapshot copies some of the pointers to registered histograms into the michael@0: // caller supplied vector (Histograms). Only histograms with names matching michael@0: // query are returned. The query must be a substring of histogram name for its michael@0: // pointer to be copied. michael@0: static void GetSnapshot(const std::string& query, Histograms* snapshot); michael@0: michael@0: michael@0: private: michael@0: // We keep all registered histograms in a map, from name to histogram. michael@0: typedef std::map HistogramMap; michael@0: michael@0: static HistogramMap* histograms_; michael@0: michael@0: // lock protects access to the above map. michael@0: static Lock* lock_; michael@0: michael@0: // Dump all known histograms to log. michael@0: static bool dump_on_exit_; michael@0: michael@0: DISALLOW_COPY_AND_ASSIGN(StatisticsRecorder); michael@0: }; michael@0: michael@0: } // namespace base michael@0: michael@0: #endif // BASE_METRICS_HISTOGRAM_H_