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/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_
    184