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 histogram_name()85 std::string histogram_name() const { return histogram_name_; } 86 87 // Operations with Flags enum. flags()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