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