Home | History | Annotate | Download | only in metrics 
      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_
    170