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