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