1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/ipc/chromium/src/base/histogram.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,781 @@
1.4 +// Copyright (c) 2011 The Chromium Authors. All rights reserved.
1.5 +// Use of this source code is governed by a BSD-style license that can be
1.6 +// found in the LICENSE file.
1.7 +
1.8 +// Histogram is an object that aggregates statistics, and can summarize them in
1.9 +// various forms, including ASCII graphical, HTML, and numerically (as a
1.10 +// vector of numbers corresponding to each of the aggregating buckets).
1.11 +
1.12 +// It supports calls to accumulate either time intervals (which are processed
1.13 +// as integral number of milliseconds), or arbitrary integral units.
1.14 +
1.15 +// The default layout of buckets is exponential. For example, buckets might
1.16 +// contain (sequentially) the count of values in the following intervals:
1.17 +// [0,1), [1,2), [2,4), [4,8), [8,16), [16,32), [32,64), [64,infinity)
1.18 +// That bucket allocation would actually result from construction of a histogram
1.19 +// for values between 1 and 64, with 8 buckets, such as:
1.20 +// Histogram count(L"some name", 1, 64, 8);
1.21 +// Note that the underflow bucket [0,1) and the overflow bucket [64,infinity)
1.22 +// are not counted by the constructor in the user supplied "bucket_count"
1.23 +// argument.
1.24 +// The above example has an exponential ratio of 2 (doubling the bucket width
1.25 +// in each consecutive bucket. The Histogram class automatically calculates
1.26 +// the smallest ratio that it can use to construct the number of buckets
1.27 +// selected in the constructor. An another example, if you had 50 buckets,
1.28 +// and millisecond time values from 1 to 10000, then the ratio between
1.29 +// consecutive bucket widths will be approximately somewhere around the 50th
1.30 +// root of 10000. This approach provides very fine grain (narrow) buckets
1.31 +// at the low end of the histogram scale, but allows the histogram to cover a
1.32 +// gigantic range with the addition of very few buckets.
1.33 +
1.34 +// Histograms use a pattern involving a function static variable, that is a
1.35 +// pointer to a histogram. This static is explicitly initialized on any thread
1.36 +// that detects a uninitialized (NULL) pointer. The potentially racy
1.37 +// initialization is not a problem as it is always set to point to the same
1.38 +// value (i.e., the FactoryGet always returns the same value). FactoryGet
1.39 +// is also completely thread safe, which results in a completely thread safe,
1.40 +// and relatively fast, set of counters. To avoid races at shutdown, the static
1.41 +// pointer is NOT deleted, and we leak the histograms at process termination.
1.42 +
1.43 +#ifndef BASE_METRICS_HISTOGRAM_H_
1.44 +#define BASE_METRICS_HISTOGRAM_H_
1.45 +#pragma once
1.46 +
1.47 +#include "mozilla/MemoryReporting.h"
1.48 +
1.49 +#include <map>
1.50 +#include <string>
1.51 +#include <vector>
1.52 +
1.53 +#include "base/time.h"
1.54 +#include "base/lock.h"
1.55 +
1.56 +class Pickle;
1.57 +
1.58 +namespace base {
1.59 +//------------------------------------------------------------------------------
1.60 +// Provide easy general purpose histogram in a macro, just like stats counters.
1.61 +// The first four macros use 50 buckets.
1.62 +
1.63 +#define HISTOGRAM_TIMES(name, sample) HISTOGRAM_CUSTOM_TIMES( \
1.64 + name, sample, base::TimeDelta::FromMilliseconds(1), \
1.65 + base::TimeDelta::FromSeconds(10), 50)
1.66 +
1.67 +#define HISTOGRAM_COUNTS(name, sample) HISTOGRAM_CUSTOM_COUNTS( \
1.68 + name, sample, 1, 1000000, 50)
1.69 +
1.70 +#define HISTOGRAM_COUNTS_100(name, sample) HISTOGRAM_CUSTOM_COUNTS( \
1.71 + name, sample, 1, 100, 50)
1.72 +
1.73 +#define HISTOGRAM_COUNTS_10000(name, sample) HISTOGRAM_CUSTOM_COUNTS( \
1.74 + name, sample, 1, 10000, 50)
1.75 +
1.76 +#define HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) do { \
1.77 + static base::Histogram* counter(NULL); \
1.78 + if (!counter) \
1.79 + counter = base::Histogram::FactoryGet(name, min, max, bucket_count, \
1.80 + base::Histogram::kNoFlags); \
1.81 + DCHECK_EQ(name, counter->histogram_name()); \
1.82 + counter->Add(sample); \
1.83 + } while (0)
1.84 +
1.85 +#define HISTOGRAM_PERCENTAGE(name, under_one_hundred) \
1.86 + HISTOGRAM_ENUMERATION(name, under_one_hundred, 101)
1.87 +
1.88 +// For folks that need real specific times, use this to select a precise range
1.89 +// of times you want plotted, and the number of buckets you want used.
1.90 +#define HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) do { \
1.91 + static base::Histogram* counter(NULL); \
1.92 + if (!counter) \
1.93 + counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \
1.94 + base::Histogram::kNoFlags); \
1.95 + DCHECK_EQ(name, counter->histogram_name()); \
1.96 + counter->AddTime(sample); \
1.97 + } while (0)
1.98 +
1.99 +// DO NOT USE THIS. It is being phased out, in favor of HISTOGRAM_CUSTOM_TIMES.
1.100 +#define HISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) do { \
1.101 + static base::Histogram* counter(NULL); \
1.102 + if (!counter) \
1.103 + counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \
1.104 + base::Histogram::kNoFlags); \
1.105 + DCHECK_EQ(name, counter->histogram_name()); \
1.106 + if ((sample) < (max)) counter->AddTime(sample); \
1.107 + } while (0)
1.108 +
1.109 +// Support histograming of an enumerated value. The samples should always be
1.110 +// less than boundary_value.
1.111 +
1.112 +#define HISTOGRAM_ENUMERATION(name, sample, boundary_value) do { \
1.113 + static base::Histogram* counter(NULL); \
1.114 + if (!counter) \
1.115 + counter = base::LinearHistogram::FactoryGet(name, 1, boundary_value, \
1.116 + boundary_value + 1, base::Histogram::kNoFlags); \
1.117 + DCHECK_EQ(name, counter->histogram_name()); \
1.118 + counter->Add(sample); \
1.119 + } while (0)
1.120 +
1.121 +#define HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) do { \
1.122 + static base::Histogram* counter(NULL); \
1.123 + if (!counter) \
1.124 + counter = base::CustomHistogram::FactoryGet(name, custom_ranges, \
1.125 + base::Histogram::kNoFlags); \
1.126 + DCHECK_EQ(name, counter->histogram_name()); \
1.127 + counter->Add(sample); \
1.128 + } while (0)
1.129 +
1.130 +
1.131 +//------------------------------------------------------------------------------
1.132 +// Define Debug vs non-debug flavors of macros.
1.133 +#ifndef NDEBUG
1.134 +
1.135 +#define DHISTOGRAM_TIMES(name, sample) HISTOGRAM_TIMES(name, sample)
1.136 +#define DHISTOGRAM_COUNTS(name, sample) HISTOGRAM_COUNTS(name, sample)
1.137 +#define DHISTOGRAM_PERCENTAGE(name, under_one_hundred) HISTOGRAM_PERCENTAGE(\
1.138 + name, under_one_hundred)
1.139 +#define DHISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \
1.140 + HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count)
1.141 +#define DHISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) \
1.142 + HISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count)
1.143 +#define DHISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \
1.144 + HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count)
1.145 +#define DHISTOGRAM_ENUMERATION(name, sample, boundary_value) \
1.146 + HISTOGRAM_ENUMERATION(name, sample, boundary_value)
1.147 +#define DHISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \
1.148 + HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges)
1.149 +
1.150 +#else // NDEBUG
1.151 +
1.152 +#define DHISTOGRAM_TIMES(name, sample) do {} while (0)
1.153 +#define DHISTOGRAM_COUNTS(name, sample) do {} while (0)
1.154 +#define DHISTOGRAM_PERCENTAGE(name, under_one_hundred) do {} while (0)
1.155 +#define DHISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) \
1.156 + do {} while (0)
1.157 +#define DHISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) \
1.158 + do {} while (0)
1.159 +#define DHISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) \
1.160 + do {} while (0)
1.161 +#define DHISTOGRAM_ENUMERATION(name, sample, boundary_value) do {} while (0)
1.162 +#define DHISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) \
1.163 + do {} while (0)
1.164 +
1.165 +#endif // NDEBUG
1.166 +
1.167 +//------------------------------------------------------------------------------
1.168 +// The following macros provide typical usage scenarios for callers that wish
1.169 +// to record histogram data, and have the data submitted/uploaded via UMA.
1.170 +// Not all systems support such UMA, but if they do, the following macros
1.171 +// should work with the service.
1.172 +
1.173 +#define UMA_HISTOGRAM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \
1.174 + name, sample, base::TimeDelta::FromMilliseconds(1), \
1.175 + base::TimeDelta::FromSeconds(10), 50)
1.176 +
1.177 +#define UMA_HISTOGRAM_MEDIUM_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \
1.178 + name, sample, base::TimeDelta::FromMilliseconds(10), \
1.179 + base::TimeDelta::FromMinutes(3), 50)
1.180 +
1.181 +// Use this macro when times can routinely be much longer than 10 seconds.
1.182 +#define UMA_HISTOGRAM_LONG_TIMES(name, sample) UMA_HISTOGRAM_CUSTOM_TIMES( \
1.183 + name, sample, base::TimeDelta::FromMilliseconds(1), \
1.184 + base::TimeDelta::FromHours(1), 50)
1.185 +
1.186 +#define UMA_HISTOGRAM_CUSTOM_TIMES(name, sample, min, max, bucket_count) do { \
1.187 + static base::Histogram* counter(NULL); \
1.188 + if (!counter) \
1.189 + counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \
1.190 + base::Histogram::kUmaTargetedHistogramFlag); \
1.191 + DCHECK_EQ(name, counter->histogram_name()); \
1.192 + counter->AddTime(sample); \
1.193 + } while (0)
1.194 +
1.195 +// DO NOT USE THIS. It is being phased out, in favor of HISTOGRAM_CUSTOM_TIMES.
1.196 +#define UMA_HISTOGRAM_CLIPPED_TIMES(name, sample, min, max, bucket_count) do { \
1.197 + static base::Histogram* counter(NULL); \
1.198 + if (!counter) \
1.199 + counter = base::Histogram::FactoryTimeGet(name, min, max, bucket_count, \
1.200 + base::Histogram::kUmaTargetedHistogramFlag); \
1.201 + DCHECK_EQ(name, counter->histogram_name()); \
1.202 + if ((sample) < (max)) counter->AddTime(sample); \
1.203 + } while (0)
1.204 +
1.205 +#define UMA_HISTOGRAM_COUNTS(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
1.206 + name, sample, 1, 1000000, 50)
1.207 +
1.208 +#define UMA_HISTOGRAM_COUNTS_100(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
1.209 + name, sample, 1, 100, 50)
1.210 +
1.211 +#define UMA_HISTOGRAM_COUNTS_10000(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
1.212 + name, sample, 1, 10000, 50)
1.213 +
1.214 +#define UMA_HISTOGRAM_CUSTOM_COUNTS(name, sample, min, max, bucket_count) do { \
1.215 + static base::Histogram* counter(NULL); \
1.216 + if (!counter) \
1.217 + counter = base::Histogram::FactoryGet(name, min, max, bucket_count, \
1.218 + base::Histogram::kUmaTargetedHistogramFlag); \
1.219 + DCHECK_EQ(name, counter->histogram_name()); \
1.220 + counter->Add(sample); \
1.221 + } while (0)
1.222 +
1.223 +#define UMA_HISTOGRAM_MEMORY_KB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
1.224 + name, sample, 1000, 500000, 50)
1.225 +
1.226 +#define UMA_HISTOGRAM_MEMORY_MB(name, sample) UMA_HISTOGRAM_CUSTOM_COUNTS( \
1.227 + name, sample, 1, 1000, 50)
1.228 +
1.229 +#define UMA_HISTOGRAM_PERCENTAGE(name, under_one_hundred) \
1.230 + UMA_HISTOGRAM_ENUMERATION(name, under_one_hundred, 101)
1.231 +
1.232 +#define UMA_HISTOGRAM_BOOLEAN(name, sample) do { \
1.233 + static base::Histogram* counter(NULL); \
1.234 + if (!counter) \
1.235 + counter = base::BooleanHistogram::FactoryGet(name, \
1.236 + base::Histogram::kUmaTargetedHistogramFlag); \
1.237 + DCHECK_EQ(name, counter->histogram_name()); \
1.238 + counter->AddBoolean(sample); \
1.239 + } while (0)
1.240 +
1.241 +#define UMA_HISTOGRAM_ENUMERATION(name, sample, boundary_value) do { \
1.242 + static base::Histogram* counter(NULL); \
1.243 + if (!counter) \
1.244 + counter = base::LinearHistogram::FactoryGet(name, 1, boundary_value, \
1.245 + boundary_value + 1, base::Histogram::kUmaTargetedHistogramFlag); \
1.246 + DCHECK_EQ(name, counter->histogram_name()); \
1.247 + counter->Add(sample); \
1.248 + } while (0)
1.249 +
1.250 +#define UMA_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges) do { \
1.251 + static base::Histogram* counter(NULL); \
1.252 + if (!counter) \
1.253 + counter = base::CustomHistogram::FactoryGet(name, custom_ranges, \
1.254 + base::Histogram::kUmaTargetedHistogramFlag); \
1.255 + DCHECK_EQ(name, counter->histogram_name()); \
1.256 + counter->Add(sample); \
1.257 + } while (0)
1.258 +
1.259 +//------------------------------------------------------------------------------
1.260 +
1.261 +class BooleanHistogram;
1.262 +class CustomHistogram;
1.263 +class Histogram;
1.264 +class LinearHistogram;
1.265 +
1.266 +class Histogram {
1.267 + public:
1.268 + typedef int Sample; // Used for samples (and ranges of samples).
1.269 + typedef int Count; // Used to count samples in a bucket.
1.270 + static const Sample kSampleType_MAX = INT_MAX;
1.271 + // Initialize maximum number of buckets in histograms as 16,384.
1.272 + static const size_t kBucketCount_MAX;
1.273 +
1.274 + typedef std::vector<Count> Counts;
1.275 + typedef std::vector<Sample> Ranges;
1.276 +
1.277 + // These enums are used to facilitate deserialization of renderer histograms
1.278 + // into the browser.
1.279 + enum ClassType {
1.280 + HISTOGRAM,
1.281 + LINEAR_HISTOGRAM,
1.282 + BOOLEAN_HISTOGRAM,
1.283 + FLAG_HISTOGRAM,
1.284 + CUSTOM_HISTOGRAM,
1.285 + NOT_VALID_IN_RENDERER
1.286 + };
1.287 +
1.288 + enum BucketLayout {
1.289 + EXPONENTIAL,
1.290 + LINEAR,
1.291 + CUSTOM
1.292 + };
1.293 +
1.294 + enum Flags {
1.295 + kNoFlags = 0,
1.296 + kUmaTargetedHistogramFlag = 0x1, // Histogram should be UMA uploaded.
1.297 + kExtendedStatisticsFlag = 0x2, // OK to gather extended statistics on histograms.
1.298 +
1.299 + // Indicate that the histogram was pickled to be sent across an IPC Channel.
1.300 + // If we observe this flag on a histogram being aggregated into after IPC,
1.301 + // then we are running in a single process mode, and the aggregation should
1.302 + // not take place (as we would be aggregating back into the source
1.303 + // histogram!).
1.304 + kIPCSerializationSourceFlag = 0x10,
1.305 +
1.306 + kHexRangePrintingFlag = 0x8000 // Fancy bucket-naming supported.
1.307 + };
1.308 +
1.309 + enum Inconsistencies {
1.310 + NO_INCONSISTENCIES = 0x0,
1.311 + RANGE_CHECKSUM_ERROR = 0x1,
1.312 + BUCKET_ORDER_ERROR = 0x2,
1.313 + COUNT_HIGH_ERROR = 0x4,
1.314 + COUNT_LOW_ERROR = 0x8,
1.315 +
1.316 + NEVER_EXCEEDED_VALUE = 0x10
1.317 + };
1.318 +
1.319 + struct DescriptionPair {
1.320 + Sample sample;
1.321 + const char* description; // Null means end of a list of pairs.
1.322 + };
1.323 +
1.324 + size_t SizeOfIncludingThis(mozilla::MallocSizeOf aMallocSizeOf);
1.325 +
1.326 + //----------------------------------------------------------------------------
1.327 + // Statistic values, developed over the life of the histogram.
1.328 +
1.329 + class SampleSet {
1.330 + public:
1.331 + explicit SampleSet();
1.332 + ~SampleSet();
1.333 +
1.334 + // Adjust size of counts_ for use with given histogram.
1.335 + void Resize(const Histogram& histogram);
1.336 + void CheckSize(const Histogram& histogram) const;
1.337 +
1.338 + // Accessor for histogram to make routine additions.
1.339 + void AccumulateWithLinearStats(Sample value, Count count, size_t index);
1.340 + // Alternate routine for exponential histograms.
1.341 + // computeExpensiveStatistics should be true if we want to compute log sums.
1.342 + void AccumulateWithExponentialStats(Sample value, Count count, size_t index,
1.343 + bool computeExtendedStatistics);
1.344 +
1.345 + // Accessor methods.
1.346 + Count counts(size_t i) const { return counts_[i]; }
1.347 + Count TotalCount() const;
1.348 + int64_t sum() const { return sum_; }
1.349 + uint64_t sum_squares() const { return sum_squares_; }
1.350 + double log_sum() const { return log_sum_; }
1.351 + double log_sum_squares() const { return log_sum_squares_; }
1.352 + int64_t redundant_count() const { return redundant_count_; }
1.353 + size_t size() const { return counts_.size(); }
1.354 +
1.355 + // Arithmetic manipulation of corresponding elements of the set.
1.356 + void Add(const SampleSet& other);
1.357 + void Subtract(const SampleSet& other);
1.358 +
1.359 + bool Serialize(Pickle* pickle) const;
1.360 + bool Deserialize(void** iter, const Pickle& pickle);
1.361 +
1.362 + size_t SizeOfExcludingThis(mozilla::MallocSizeOf aMallocSizeOf);
1.363 +
1.364 + protected:
1.365 + // Actual histogram data is stored in buckets, showing the count of values
1.366 + // that fit into each bucket.
1.367 + Counts counts_;
1.368 +
1.369 + // Save simple stats locally. Note that this MIGHT get done in base class
1.370 + // without shared memory at some point.
1.371 + int64_t sum_; // sum of samples.
1.372 + uint64_t sum_squares_; // sum of squares of samples.
1.373 +
1.374 + // These fields may or may not be updated at the discretion of the
1.375 + // histogram. We use the natural log and compute ln(sample+1) so that
1.376 + // zeros are handled sanely.
1.377 + double log_sum_; // sum of logs of samples.
1.378 + double log_sum_squares_; // sum of squares of logs of samples
1.379 +
1.380 + private:
1.381 + void Accumulate(Sample value, Count count, size_t index);
1.382 +
1.383 + // To help identify memory corruption, we reduntantly save the number of
1.384 + // samples we've accumulated into all of our buckets. We can compare this
1.385 + // count to the sum of the counts in all buckets, and detect problems. Note
1.386 + // that due to races in histogram accumulation (if a histogram is indeed
1.387 + // updated on several threads simultaneously), the tallies might mismatch,
1.388 + // and also the snapshotting code may asynchronously get a mismatch (though
1.389 + // generally either race based mismatch cause is VERY rare).
1.390 + int64_t redundant_count_;
1.391 + };
1.392 +
1.393 + //----------------------------------------------------------------------------
1.394 + // minimum should start from 1. 0 is invalid as a minimum. 0 is an implicit
1.395 + // default underflow bucket.
1.396 + static Histogram* FactoryGet(const std::string& name,
1.397 + Sample minimum,
1.398 + Sample maximum,
1.399 + size_t bucket_count,
1.400 + Flags flags);
1.401 + static Histogram* FactoryTimeGet(const std::string& name,
1.402 + base::TimeDelta minimum,
1.403 + base::TimeDelta maximum,
1.404 + size_t bucket_count,
1.405 + Flags flags);
1.406 +
1.407 + void Add(int value);
1.408 + void Subtract(int value);
1.409 +
1.410 + // This method is an interface, used only by BooleanHistogram.
1.411 + virtual void AddBoolean(bool value);
1.412 +
1.413 + // Accept a TimeDelta to increment.
1.414 + void AddTime(TimeDelta time) {
1.415 + Add(static_cast<int>(time.InMilliseconds()));
1.416 + }
1.417 +
1.418 + virtual void AddSampleSet(const SampleSet& sample);
1.419 +
1.420 + void Clear();
1.421 +
1.422 + // This method is an interface, used only by LinearHistogram.
1.423 + virtual void SetRangeDescriptions(const DescriptionPair descriptions[]);
1.424 +
1.425 + // The following methods provide graphical histogram displays.
1.426 + void WriteHTMLGraph(std::string* output) const;
1.427 + void WriteAscii(bool graph_it, const std::string& newline,
1.428 + std::string* output) const;
1.429 +
1.430 + // Support generic flagging of Histograms.
1.431 + // 0x1 Currently used to mark this histogram to be recorded by UMA..
1.432 + // 0x8000 means print ranges in hex.
1.433 + void SetFlags(Flags flags) { flags_ = static_cast<Flags> (flags_ | flags); }
1.434 + void ClearFlags(Flags flags) { flags_ = static_cast<Flags>(flags_ & ~flags); }
1.435 + int flags() const { return flags_; }
1.436 +
1.437 + // Convenience methods for serializing/deserializing the histograms.
1.438 + // Histograms from Renderer process are serialized and sent to the browser.
1.439 + // Browser process reconstructs the histogram from the pickled version
1.440 + // accumulates the browser-side shadow copy of histograms (that mirror
1.441 + // histograms created in the renderer).
1.442 +
1.443 + // Serialize the given snapshot of a Histogram into a String. Uses
1.444 + // Pickle class to flatten the object.
1.445 + static std::string SerializeHistogramInfo(const Histogram& histogram,
1.446 + const SampleSet& snapshot);
1.447 + // The following method accepts a list of pickled histograms and
1.448 + // builds a histogram and updates shadow copy of histogram data in the
1.449 + // browser process.
1.450 + static bool DeserializeHistogramInfo(const std::string& histogram_info);
1.451 +
1.452 + // Check to see if bucket ranges, counts and tallies in the snapshot are
1.453 + // consistent with the bucket ranges and checksums in our histogram. This can
1.454 + // produce a false-alarm if a race occurred in the reading of the data during
1.455 + // a SnapShot process, but should otherwise be false at all times (unless we
1.456 + // have memory over-writes, or DRAM failures).
1.457 + virtual Inconsistencies FindCorruption(const SampleSet& snapshot) const;
1.458 +
1.459 + //----------------------------------------------------------------------------
1.460 + // Accessors for factory constuction, serialization and testing.
1.461 + //----------------------------------------------------------------------------
1.462 + virtual ClassType histogram_type() const;
1.463 + const std::string& histogram_name() const { return histogram_name_; }
1.464 + Sample declared_min() const { return declared_min_; }
1.465 + Sample declared_max() const { return declared_max_; }
1.466 + virtual Sample ranges(size_t i) const;
1.467 + uint32_t range_checksum() const { return range_checksum_; }
1.468 + virtual size_t bucket_count() const;
1.469 + // Snapshot the current complete set of sample data.
1.470 + // Override with atomic/locked snapshot if needed.
1.471 + virtual void SnapshotSample(SampleSet* sample) const;
1.472 +
1.473 + virtual bool HasConstructorArguments(Sample minimum, Sample maximum,
1.474 + size_t bucket_count);
1.475 +
1.476 + virtual bool HasConstructorTimeDeltaArguments(TimeDelta minimum,
1.477 + TimeDelta maximum,
1.478 + size_t bucket_count);
1.479 + // Return true iff the range_checksum_ matches current ranges_ vector.
1.480 + bool HasValidRangeChecksum() const;
1.481 +
1.482 + protected:
1.483 + Histogram(const std::string& name, Sample minimum,
1.484 + Sample maximum, size_t bucket_count);
1.485 + Histogram(const std::string& name, TimeDelta minimum,
1.486 + TimeDelta maximum, size_t bucket_count);
1.487 +
1.488 + virtual ~Histogram();
1.489 +
1.490 + // Initialize ranges_ mapping.
1.491 + void InitializeBucketRange();
1.492 +
1.493 + // Method to override to skip the display of the i'th bucket if it's empty.
1.494 + virtual bool PrintEmptyBucket(size_t index) const;
1.495 +
1.496 + //----------------------------------------------------------------------------
1.497 + // Methods to override to create histogram with different bucket widths.
1.498 + //----------------------------------------------------------------------------
1.499 + // Find bucket to increment for sample value.
1.500 + virtual size_t BucketIndex(Sample value) const;
1.501 + // Get normalized size, relative to the ranges_[i].
1.502 + virtual double GetBucketSize(Count current, size_t i) const;
1.503 +
1.504 + // Recalculate range_checksum_.
1.505 + void ResetRangeChecksum();
1.506 +
1.507 + // Return a string description of what goes in a given bucket.
1.508 + // Most commonly this is the numeric value, but in derived classes it may
1.509 + // be a name (or string description) given to the bucket.
1.510 + virtual const std::string GetAsciiBucketRange(size_t it) const;
1.511 +
1.512 + //----------------------------------------------------------------------------
1.513 + // Methods to override to create thread safe histogram.
1.514 + //----------------------------------------------------------------------------
1.515 + // Update all our internal data, including histogram
1.516 + virtual void Accumulate(Sample value, Count count, size_t index);
1.517 +
1.518 + //----------------------------------------------------------------------------
1.519 + // Accessors for derived classes.
1.520 + //----------------------------------------------------------------------------
1.521 + void SetBucketRange(size_t i, Sample value);
1.522 +
1.523 + // Validate that ranges_ was created sensibly (top and bottom range
1.524 + // values relate properly to the declared_min_ and declared_max_)..
1.525 + bool ValidateBucketRanges() const;
1.526 +
1.527 + virtual uint32_t CalculateRangeChecksum() const;
1.528 +
1.529 + // Finally, provide the state that changes with the addition of each new
1.530 + // sample.
1.531 + SampleSet sample_;
1.532 +
1.533 + private:
1.534 + friend class StatisticsRecorder; // To allow it to delete duplicates.
1.535 +
1.536 + // Post constructor initialization.
1.537 + void Initialize();
1.538 +
1.539 + // Checksum function for accumulating range values into a checksum.
1.540 + static uint32_t Crc32(uint32_t sum, Sample range);
1.541 +
1.542 + //----------------------------------------------------------------------------
1.543 + // Helpers for emitting Ascii graphic. Each method appends data to output.
1.544 +
1.545 + // Find out how large the (graphically) the largest bucket will appear to be.
1.546 + double GetPeakBucketSize(const SampleSet& snapshot) const;
1.547 +
1.548 + // Write a common header message describing this histogram.
1.549 + void WriteAsciiHeader(const SampleSet& snapshot,
1.550 + Count sample_count, std::string* output) const;
1.551 +
1.552 + // Write information about previous, current, and next buckets.
1.553 + // Information such as cumulative percentage, etc.
1.554 + void WriteAsciiBucketContext(const int64_t past, const Count current,
1.555 + const int64_t remaining, const size_t i,
1.556 + std::string* output) const;
1.557 +
1.558 + // Write textual description of the bucket contents (relative to histogram).
1.559 + // Output is the count in the buckets, as well as the percentage.
1.560 + void WriteAsciiBucketValue(Count current, double scaled_sum,
1.561 + std::string* output) const;
1.562 +
1.563 + // Produce actual graph (set of blank vs non blank char's) for a bucket.
1.564 + void WriteAsciiBucketGraph(double current_size, double max_size,
1.565 + std::string* output) const;
1.566 +
1.567 + //----------------------------------------------------------------------------
1.568 + // Table for generating Crc32 values.
1.569 + static const uint32_t kCrcTable[256];
1.570 + //----------------------------------------------------------------------------
1.571 + // Invariant values set at/near construction time
1.572 +
1.573 + // ASCII version of original name given to the constructor. All identically
1.574 + // named instances will be coalesced cross-project.
1.575 + const std::string histogram_name_;
1.576 + Sample declared_min_; // Less than this goes into counts_[0]
1.577 + Sample declared_max_; // Over this goes into counts_[bucket_count_ - 1].
1.578 + size_t bucket_count_; // Dimension of counts_[].
1.579 +
1.580 + // Flag the histogram for recording by UMA via metric_services.h.
1.581 + Flags flags_;
1.582 +
1.583 + // For each index, show the least value that can be stored in the
1.584 + // corresponding bucket. We also append one extra element in this array,
1.585 + // containing kSampleType_MAX, to make calculations easy.
1.586 + // The dimension of ranges_ is bucket_count + 1.
1.587 + Ranges ranges_;
1.588 +
1.589 + // For redundancy, we store a checksum of all the sample ranges when ranges
1.590 + // are generated. If ever there is ever a difference, then the histogram must
1.591 + // have been corrupted.
1.592 + uint32_t range_checksum_;
1.593 +
1.594 + DISALLOW_COPY_AND_ASSIGN(Histogram);
1.595 +};
1.596 +
1.597 +//------------------------------------------------------------------------------
1.598 +
1.599 +// LinearHistogram is a more traditional histogram, with evenly spaced
1.600 +// buckets.
1.601 +class LinearHistogram : public Histogram {
1.602 + public:
1.603 + virtual ~LinearHistogram();
1.604 +
1.605 + /* minimum should start from 1. 0 is as minimum is invalid. 0 is an implicit
1.606 + default underflow bucket. */
1.607 + static Histogram* FactoryGet(const std::string& name,
1.608 + Sample minimum,
1.609 + Sample maximum,
1.610 + size_t bucket_count,
1.611 + Flags flags);
1.612 + static Histogram* FactoryTimeGet(const std::string& name,
1.613 + TimeDelta minimum,
1.614 + TimeDelta maximum,
1.615 + size_t bucket_count,
1.616 + Flags flags);
1.617 +
1.618 + // Overridden from Histogram:
1.619 + virtual ClassType histogram_type() const;
1.620 +
1.621 + virtual void Accumulate(Sample value, Count count, size_t index);
1.622 +
1.623 + // Store a list of number/text values for use in rendering the histogram.
1.624 + // The last element in the array has a null in its "description" slot.
1.625 + virtual void SetRangeDescriptions(const DescriptionPair descriptions[]);
1.626 +
1.627 + protected:
1.628 + LinearHistogram(const std::string& name, Sample minimum,
1.629 + Sample maximum, size_t bucket_count);
1.630 +
1.631 + LinearHistogram(const std::string& name, TimeDelta minimum,
1.632 + TimeDelta maximum, size_t bucket_count);
1.633 +
1.634 + // Initialize ranges_ mapping.
1.635 + void InitializeBucketRange();
1.636 + virtual double GetBucketSize(Count current, size_t i) const;
1.637 +
1.638 + // If we have a description for a bucket, then return that. Otherwise
1.639 + // let parent class provide a (numeric) description.
1.640 + virtual const std::string GetAsciiBucketRange(size_t i) const;
1.641 +
1.642 + // Skip printing of name for numeric range if we have a name (and if this is
1.643 + // an empty bucket).
1.644 + virtual bool PrintEmptyBucket(size_t index) const;
1.645 +
1.646 + private:
1.647 + // For some ranges, we store a printable description of a bucket range.
1.648 + // If there is no desciption, then GetAsciiBucketRange() uses parent class
1.649 + // to provide a description.
1.650 + typedef std::map<Sample, std::string> BucketDescriptionMap;
1.651 + BucketDescriptionMap bucket_description_;
1.652 +
1.653 + DISALLOW_COPY_AND_ASSIGN(LinearHistogram);
1.654 +};
1.655 +
1.656 +//------------------------------------------------------------------------------
1.657 +
1.658 +// BooleanHistogram is a histogram for booleans.
1.659 +class BooleanHistogram : public LinearHistogram {
1.660 + public:
1.661 + static Histogram* FactoryGet(const std::string& name, Flags flags);
1.662 +
1.663 + virtual ClassType histogram_type() const;
1.664 +
1.665 + virtual void AddBoolean(bool value);
1.666 +
1.667 + virtual void Accumulate(Sample value, Count count, size_t index);
1.668 +
1.669 + protected:
1.670 + explicit BooleanHistogram(const std::string& name);
1.671 +
1.672 + DISALLOW_COPY_AND_ASSIGN(BooleanHistogram);
1.673 +};
1.674 +
1.675 +//------------------------------------------------------------------------------
1.676 +
1.677 +// FlagHistogram is like boolean histogram, but only allows a single off/on value.
1.678 +class FlagHistogram : public BooleanHistogram
1.679 +{
1.680 +public:
1.681 + static Histogram *FactoryGet(const std::string &name, Flags flags);
1.682 +
1.683 + virtual ClassType histogram_type() const;
1.684 +
1.685 + virtual void Accumulate(Sample value, Count count, size_t index);
1.686 +
1.687 + virtual void AddSampleSet(const SampleSet& sample);
1.688 +
1.689 +private:
1.690 + explicit FlagHistogram(const std::string &name);
1.691 + bool mSwitched;
1.692 +
1.693 + DISALLOW_COPY_AND_ASSIGN(FlagHistogram);
1.694 +};
1.695 +
1.696 +//------------------------------------------------------------------------------
1.697 +
1.698 +// CustomHistogram is a histogram for a set of custom integers.
1.699 +class CustomHistogram : public Histogram {
1.700 + public:
1.701 +
1.702 + static Histogram* FactoryGet(const std::string& name,
1.703 + const std::vector<Sample>& custom_ranges,
1.704 + Flags flags);
1.705 +
1.706 + // Overridden from Histogram:
1.707 + virtual ClassType histogram_type() const;
1.708 +
1.709 + protected:
1.710 + CustomHistogram(const std::string& name,
1.711 + const std::vector<Sample>& custom_ranges);
1.712 +
1.713 + // Initialize ranges_ mapping.
1.714 + void InitializedCustomBucketRange(const std::vector<Sample>& custom_ranges);
1.715 + virtual double GetBucketSize(Count current, size_t i) const;
1.716 +
1.717 + DISALLOW_COPY_AND_ASSIGN(CustomHistogram);
1.718 +};
1.719 +
1.720 +//------------------------------------------------------------------------------
1.721 +// StatisticsRecorder handles all histograms in the system. It provides a
1.722 +// general place for histograms to register, and supports a global API for
1.723 +// accessing (i.e., dumping, or graphing) the data in all the histograms.
1.724 +
1.725 +class StatisticsRecorder {
1.726 + public:
1.727 + typedef std::vector<Histogram*> Histograms;
1.728 +
1.729 + StatisticsRecorder();
1.730 +
1.731 + ~StatisticsRecorder();
1.732 +
1.733 + // Find out if histograms can now be registered into our list.
1.734 + static bool IsActive();
1.735 +
1.736 + // Register, or add a new histogram to the collection of statistics. If an
1.737 + // identically named histogram is already registered, then the argument
1.738 + // |histogram| will deleted. The returned value is always the registered
1.739 + // histogram (either the argument, or the pre-existing registered histogram).
1.740 + static Histogram* RegisterOrDeleteDuplicate(Histogram* histogram);
1.741 +
1.742 + // Methods for printing histograms. Only histograms which have query as
1.743 + // a substring are written to output (an empty string will process all
1.744 + // registered histograms).
1.745 + static void WriteHTMLGraph(const std::string& query, std::string* output);
1.746 + static void WriteGraph(const std::string& query, std::string* output);
1.747 +
1.748 + // Method for extracting histograms which were marked for use by UMA.
1.749 + static void GetHistograms(Histograms* output);
1.750 +
1.751 + // Find a histogram by name. It matches the exact name. This method is thread
1.752 + // safe. If a matching histogram is not found, then the |histogram| is
1.753 + // not changed.
1.754 + static bool FindHistogram(const std::string& query, Histogram** histogram);
1.755 +
1.756 + static bool dump_on_exit() { return dump_on_exit_; }
1.757 +
1.758 + static void set_dump_on_exit(bool enable) { dump_on_exit_ = enable; }
1.759 +
1.760 + // GetSnapshot copies some of the pointers to registered histograms into the
1.761 + // caller supplied vector (Histograms). Only histograms with names matching
1.762 + // query are returned. The query must be a substring of histogram name for its
1.763 + // pointer to be copied.
1.764 + static void GetSnapshot(const std::string& query, Histograms* snapshot);
1.765 +
1.766 +
1.767 + private:
1.768 + // We keep all registered histograms in a map, from name to histogram.
1.769 + typedef std::map<std::string, Histogram*> HistogramMap;
1.770 +
1.771 + static HistogramMap* histograms_;
1.772 +
1.773 + // lock protects access to the above map.
1.774 + static Lock* lock_;
1.775 +
1.776 + // Dump all known histograms to log.
1.777 + static bool dump_on_exit_;
1.778 +
1.779 + DISALLOW_COPY_AND_ASSIGN(StatisticsRecorder);
1.780 +};
1.781 +
1.782 +} // namespace base
1.783 +
1.784 +#endif // BASE_METRICS_HISTOGRAM_H_
