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 histogram_name()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. flags()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