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