base/metrics/histogram_base.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_METRICS_HISTOGRAM_BASE_H_
   6 #define BASE_METRICS_HISTOGRAM_BASE_H_
   7
   8 #include <stdint.h>
   9
  10 #include <string>
  11 #include <vector>
  12
  13 #include "base/atomicops.h"
  14 #include "base/base_export.h"
  15 #include "base/basictypes.h"
  16 #include "base/memory/scoped_ptr.h"
  17 #include "base/strings/string_piece.h"
  18 #include "base/time/time.h"
  19
  20 namespace base {
  21
  22 class DictionaryValue;
  23 class HistogramBase;
  24 class HistogramSamples;
  25 class ListValue;
  26 class Pickle;
  27 class PickleIterator;
  28
  29 ////////////////////////////////////////////////////////////////////////////////
  30 // These enums are used to facilitate deserialization of histograms from other
  31 // processes into the browser. If you create another class that inherits from
  32 // HistogramBase, add new histogram types and names below.
  33
  34 enum HistogramType {
  35   HISTOGRAM,
  36   LINEAR_HISTOGRAM,
  37   BOOLEAN_HISTOGRAM,
  38   CUSTOM_HISTOGRAM,
  39   SPARSE_HISTOGRAM,
  40 };
  41
  42 std::string HistogramTypeToString(HistogramType type);
  43
  44 // Create or find existing histogram that matches the pickled info.
  45 // Returns NULL if the pickled data has problems.
  46 BASE_EXPORT_PRIVATE HistogramBase* DeserializeHistogramInfo(
  47     base::PickleIterator* iter);
  48
  49 ////////////////////////////////////////////////////////////////////////////////
  50
  51 class BASE_EXPORT HistogramBase {
  52  public:
  53   typedef int32_t Sample;                // Used for samples.
  54   typedef subtle::Atomic32 AtomicCount;  // Used to count samples.
  55   typedef int32_t Count;  // Used to manipulate counts in temporaries.
  56
  57   static const Sample kSampleType_MAX;  // INT_MAX
  58
  59   enum Flags {
  60     kNoFlags = 0,
  61
  62     // Histogram should be UMA uploaded.
  63     kUmaTargetedHistogramFlag = 0x1,
  64
  65     // Indicates that this is a stability histogram. This flag exists to specify
  66     // which histograms should be included in the initial stability log. Please
  67     // refer to |MetricsService::PrepareInitialStabilityLog|.
  68     kUmaStabilityHistogramFlag = kUmaTargetedHistogramFlag | 0x2,
  69
  70     // Indicates that the histogram was pickled to be sent across an IPC
  71     // Channel. If we observe this flag on a histogram being aggregated into
  72     // after IPC, then we are running in a single process mode, and the
  73     // aggregation should not take place (as we would be aggregating back into
  74     // the source histogram!).
  75     kIPCSerializationSourceFlag = 0x10,
  76
  77     // Indicates that a callback exists for when a new sample is recorded on
  78     // this histogram. We store this as a flag with the histogram since
  79     // histograms can be in performance critical code, and this allows us
  80     // to shortcut looking up the callback if it doesn't exist.
  81     kCallbackExists = 0x20,
  82
  83     // Only for Histogram and its sub classes: fancy bucket-naming support.
  84     kHexRangePrintingFlag = 0x8000,
  85   };
  86
  87   // Histogram data inconsistency types.
  88   enum Inconsistency {
  89     NO_INCONSISTENCIES = 0x0,
  90     RANGE_CHECKSUM_ERROR = 0x1,
  91     BUCKET_ORDER_ERROR = 0x2,
  92     COUNT_HIGH_ERROR = 0x4,
  93     COUNT_LOW_ERROR = 0x8,
  94
  95     NEVER_EXCEEDED_VALUE = 0x10
  96   };
  97
  98   explicit HistogramBase(const std::string& name);
  99   virtual ~HistogramBase();
 100
 101   const std::string& histogram_name() const { return histogram_name_; }
 102
 103   // Comapres |name| to the histogram name and triggers a DCHECK if they do not
 104   // match. This is a helper function used by histogram macros, which results in
 105   // in more compact machine code being generated by the macros.
 106   void CheckName(const StringPiece& name) const;
 107
 108   // Operations with Flags enum.
 109   int32_t flags() const { return flags_; }
 110   void SetFlags(int32_t flags);
 111   void ClearFlags(int32_t flags);
 112
 113   virtual HistogramType GetHistogramType() const = 0;
 114
 115   // Whether the histogram has construction arguments as parameters specified.
 116   // For histograms that don't have the concept of minimum, maximum or
 117   // bucket_count, this function always returns false.
 118   virtual bool HasConstructionArguments(Sample expected_minimum,
 119                                         Sample expected_maximum,
 120                                         size_t expected_bucket_count) const = 0;
 121
 122   virtual void Add(Sample value) = 0;
 123
 124   // In Add function the |value| bucket is increased by one, but in some use
 125   // cases we need to increase this value by an arbitrary integer. AddCount
 126   // function increases the |value| bucket by |count|. |count| should be greater
 127   // than or equal to 1.
 128   virtual void AddCount(Sample value, int count) = 0;
 129
 130   // 2 convenient functions that call Add(Sample).
 131   void AddTime(const TimeDelta& time);
 132   void AddBoolean(bool value);
 133
 134   virtual void AddSamples(const HistogramSamples& samples) = 0;
 135   virtual bool AddSamplesFromPickle(base::PickleIterator* iter) = 0;
 136
 137   // Serialize the histogram info into |pickle|.
 138   // Note: This only serializes the construction arguments of the histogram, but
 139   // does not serialize the samples.
 140   bool SerializeInfo(base::Pickle* pickle) const;
 141
 142   // Try to find out data corruption from histogram and the samples.
 143   // The returned value is a combination of Inconsistency enum.
 144   virtual int FindCorruption(const HistogramSamples& samples) const;
 145
 146   // Snapshot the current complete set of sample data.
 147   // Override with atomic/locked snapshot if needed.
 148   virtual scoped_ptr<HistogramSamples> SnapshotSamples() const = 0;
 149
 150   // The following methods provide graphical histogram displays.
 151   virtual void WriteHTMLGraph(std::string* output) const = 0;
 152   virtual void WriteAscii(std::string* output) const = 0;
 153
 154   // Produce a JSON representation of the histogram. This is implemented with
 155   // the help of GetParameters and GetCountAndBucketData; overwrite them to
 156   // customize the output.
 157   void WriteJSON(std::string* output) const;
 158
 159  protected:
 160   // Subclasses should implement this function to make SerializeInfo work.
 161   virtual bool SerializeInfoImpl(base::Pickle* pickle) const = 0;
 162
 163   // Writes information about the construction parameters in |params|.
 164   virtual void GetParameters(DictionaryValue* params) const = 0;
 165
 166   // Writes information about the current (non-empty) buckets and their sample
 167   // counts to |buckets|, the total sample count to |count| and the total sum
 168   // to |sum|.
 169   virtual void GetCountAndBucketData(Count* count,
 170                                      int64* sum,
 171                                      ListValue* buckets) const = 0;
 172
 173   //// Produce actual graph (set of blank vs non blank char's) for a bucket.
 174   void WriteAsciiBucketGraph(double current_size,
 175                              double max_size,
 176                              std::string* output) const;
 177
 178   // Return a string description of what goes in a given bucket.
 179   const std::string GetSimpleAsciiBucketRange(Sample sample) const;
 180
 181   // Write textual description of the bucket contents (relative to histogram).
 182   // Output is the count in the buckets, as well as the percentage.
 183   void WriteAsciiBucketValue(Count current,
 184                              double scaled_sum,
 185                              std::string* output) const;
 186
 187   // Retrieves the callback for this histogram, if one exists, and runs it
 188   // passing |sample| as the parameter.
 189   void FindAndRunCallback(Sample sample) const;
 190
 191  private:
 192   const std::string histogram_name_;
 193   int32_t flags_;
 194
 195   DISALLOW_COPY_AND_ASSIGN(HistogramBase);
 196 };
 197
 198 }  // namespace base
 199
 200 #endif  // BASE_METRICS_HISTOGRAM_BASE_H_