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 <limits.h> 9 #include <stddef.h> 10 #include <stdint.h> 11 12 #include <memory> 13 #include <string> 14 #include <vector> 15 16 #include "base/atomicops.h" 17 #include "base/base_export.h" 18 #include "base/macros.h" 19 #include "base/strings/string_piece.h" 20 #include "base/time/time.h" 21 22 namespace base { 23 24 class BucketRanges; 25 class DictionaryValue; 26 class HistogramBase; 27 class HistogramSamples; 28 class ListValue; 29 class Pickle; 30 class PickleIterator; 31 32 //////////////////////////////////////////////////////////////////////////////// 33 // This enum is used to facilitate deserialization of histograms from other 34 // processes into the browser. If you create another class that inherits from 35 // HistogramBase, add new histogram types and names below. 36 37 enum HistogramType { 38 HISTOGRAM, 39 LINEAR_HISTOGRAM, 40 BOOLEAN_HISTOGRAM, 41 CUSTOM_HISTOGRAM, 42 SPARSE_HISTOGRAM, 43 }; 44 45 std::string HistogramTypeToString(HistogramType type); 46 47 // This enum is used for reporting how many histograms and of what types and 48 // variations are being created. It has to be in the main .h file so it is 49 // visible to files that define the various histogram types. 50 enum HistogramReport { 51 // Count the number of reports created. The other counts divided by this 52 // number will give the average per run of the program. 53 HISTOGRAM_REPORT_CREATED = 0, 54 55 // Count the total number of histograms created. It is the limit against 56 // which all others are compared. 57 HISTOGRAM_REPORT_HISTOGRAM_CREATED = 1, 58 59 // Count the total number of histograms looked-up. It's better to cache 60 // the result of a single lookup rather than do it repeatedly. 61 HISTOGRAM_REPORT_HISTOGRAM_LOOKUP = 2, 62 63 // These count the individual histogram types. This must follow the order 64 // of HistogramType above. 65 HISTOGRAM_REPORT_TYPE_LOGARITHMIC = 3, 66 HISTOGRAM_REPORT_TYPE_LINEAR = 4, 67 HISTOGRAM_REPORT_TYPE_BOOLEAN = 5, 68 HISTOGRAM_REPORT_TYPE_CUSTOM = 6, 69 HISTOGRAM_REPORT_TYPE_SPARSE = 7, 70 71 // These indicate the individual flags that were set. 72 HISTOGRAM_REPORT_FLAG_UMA_TARGETED = 8, 73 HISTOGRAM_REPORT_FLAG_UMA_STABILITY = 9, 74 HISTOGRAM_REPORT_FLAG_PERSISTENT = 10, 75 76 // This must be last. 77 HISTOGRAM_REPORT_MAX = 11 78 }; 79 80 // Create or find existing histogram that matches the pickled info. 81 // Returns NULL if the pickled data has problems. 82 BASE_EXPORT HistogramBase* DeserializeHistogramInfo(base::PickleIterator* iter); 83 84 //////////////////////////////////////////////////////////////////////////////// 85 86 class BASE_EXPORT HistogramBase { 87 public: 88 typedef int32_t Sample; // Used for samples. 89 typedef subtle::Atomic32 AtomicCount; // Used to count samples. 90 typedef int32_t Count; // Used to manipulate counts in temporaries. 91 92 static const Sample kSampleType_MAX; // INT_MAX 93 94 enum Flags { 95 kNoFlags = 0, 96 97 // Histogram should be UMA uploaded. 98 kUmaTargetedHistogramFlag = 0x1, 99 100 // Indicates that this is a stability histogram. This flag exists to specify 101 // which histograms should be included in the initial stability log. Please 102 // refer to |MetricsService::PrepareInitialStabilityLog|. 103 kUmaStabilityHistogramFlag = kUmaTargetedHistogramFlag | 0x2, 104 105 // Indicates that the histogram was pickled to be sent across an IPC 106 // Channel. If we observe this flag on a histogram being aggregated into 107 // after IPC, then we are running in a single process mode, and the 108 // aggregation should not take place (as we would be aggregating back into 109 // the source histogram!). 110 kIPCSerializationSourceFlag = 0x10, 111 112 // Indicates that a callback exists for when a new sample is recorded on 113 // this histogram. We store this as a flag with the histogram since 114 // histograms can be in performance critical code, and this allows us 115 // to shortcut looking up the callback if it doesn't exist. 116 kCallbackExists = 0x20, 117 118 // Indicates that the histogram is held in "persistent" memory and may 119 // be accessible between processes. This is only possible if such a 120 // memory segment has been created/attached, used to create a Persistent- 121 // MemoryAllocator, and that loaded into the Histogram module before this 122 // histogram is created. 123 kIsPersistent = 0x40, 124 125 // Only for Histogram and its sub classes: fancy bucket-naming support. 126 kHexRangePrintingFlag = 0x8000, 127 }; 128 129 // Histogram data inconsistency types. 130 enum Inconsistency : uint32_t { 131 NO_INCONSISTENCIES = 0x0, 132 RANGE_CHECKSUM_ERROR = 0x1, 133 BUCKET_ORDER_ERROR = 0x2, 134 COUNT_HIGH_ERROR = 0x4, 135 COUNT_LOW_ERROR = 0x8, 136 137 NEVER_EXCEEDED_VALUE = 0x10, 138 }; 139 140 explicit HistogramBase(const std::string& name); 141 virtual ~HistogramBase(); 142 143 const std::string& histogram_name() const { return histogram_name_; } 144 145 // Comapres |name| to the histogram name and triggers a DCHECK if they do not 146 // match. This is a helper function used by histogram macros, which results in 147 // in more compact machine code being generated by the macros. 148 void CheckName(const StringPiece& name) const; 149 150 // Get a unique ID for this histogram's samples. 151 virtual uint64_t name_hash() const = 0; 152 153 // Operations with Flags enum. 154 int32_t flags() const { return subtle::NoBarrier_Load(&flags_); } 155 void SetFlags(int32_t flags); 156 void ClearFlags(int32_t flags); 157 158 virtual HistogramType GetHistogramType() const = 0; 159 160 // Whether the histogram has construction arguments as parameters specified. 161 // For histograms that don't have the concept of minimum, maximum or 162 // bucket_count, this function always returns false. 163 virtual bool HasConstructionArguments( 164 Sample expected_minimum, 165 Sample expected_maximum, 166 uint32_t expected_bucket_count) const = 0; 167 168 virtual void Add(Sample value) = 0; 169 170 // In Add function the |value| bucket is increased by one, but in some use 171 // cases we need to increase this value by an arbitrary integer. AddCount 172 // function increases the |value| bucket by |count|. |count| should be greater 173 // than or equal to 1. 174 virtual void AddCount(Sample value, int count) = 0; 175 176 // 2 convenient functions that call Add(Sample). 177 void AddTime(const TimeDelta& time); 178 void AddBoolean(bool value); 179 180 virtual void AddSamples(const HistogramSamples& samples) = 0; 181 virtual bool AddSamplesFromPickle(base::PickleIterator* iter) = 0; 182 183 // Serialize the histogram info into |pickle|. 184 // Note: This only serializes the construction arguments of the histogram, but 185 // does not serialize the samples. 186 bool SerializeInfo(base::Pickle* pickle) const; 187 188 // Try to find out data corruption from histogram and the samples. 189 // The returned value is a combination of Inconsistency enum. 190 virtual uint32_t FindCorruption(const HistogramSamples& samples) const; 191 192 // Snapshot the current complete set of sample data. 193 // Override with atomic/locked snapshot if needed. 194 virtual std::unique_ptr<HistogramSamples> SnapshotSamples() const = 0; 195 196 // Calculate the change (delta) in histogram counts since the previous call 197 // to this method. Each successive call will return only those counts 198 // changed since the last call. 199 virtual std::unique_ptr<HistogramSamples> SnapshotDelta() = 0; 200 201 // Calculate the change (delta) in histogram counts since the previous call 202 // to SnapshotDelta() but do so without modifying any internal data as to 203 // what was previous logged. After such a call, no further calls to this 204 // method or to SnapshotDelta() should be done as the result would include 205 // data previously returned. Because no internal data is changed, this call 206 // can be made on "const" histograms such as those with data held in 207 // read-only memory. 208 virtual std::unique_ptr<HistogramSamples> SnapshotFinalDelta() const = 0; 209 210 // The following methods provide graphical histogram displays. 211 virtual void WriteHTMLGraph(std::string* output) const = 0; 212 virtual void WriteAscii(std::string* output) const = 0; 213 214 // Produce a JSON representation of the histogram. This is implemented with 215 // the help of GetParameters and GetCountAndBucketData; overwrite them to 216 // customize the output. 217 void WriteJSON(std::string* output) const; 218 219 // This enables a histogram that reports the what types of histograms are 220 // created and their flags. It must be called while still single-threaded. 221 // 222 // IMPORTANT: Callers must update tools/metrics/histograms/histograms.xml 223 // with the following histogram: 224 // UMA.Histograms.process_type.Creations 225 static void EnableActivityReportHistogram(const std::string& process_type); 226 227 protected: 228 enum ReportActivity { HISTOGRAM_CREATED, HISTOGRAM_LOOKUP }; 229 230 // Subclasses should implement this function to make SerializeInfo work. 231 virtual bool SerializeInfoImpl(base::Pickle* pickle) const = 0; 232 233 // Writes information about the construction parameters in |params|. 234 virtual void GetParameters(DictionaryValue* params) const = 0; 235 236 // Writes information about the current (non-empty) buckets and their sample 237 // counts to |buckets|, the total sample count to |count| and the total sum 238 // to |sum|. 239 virtual void GetCountAndBucketData(Count* count, 240 int64_t* sum, 241 ListValue* buckets) const = 0; 242 243 //// Produce actual graph (set of blank vs non blank char's) for a bucket. 244 void WriteAsciiBucketGraph(double current_size, 245 double max_size, 246 std::string* output) const; 247 248 // Return a string description of what goes in a given bucket. 249 const std::string GetSimpleAsciiBucketRange(Sample sample) const; 250 251 // Write textual description of the bucket contents (relative to histogram). 252 // Output is the count in the buckets, as well as the percentage. 253 void WriteAsciiBucketValue(Count current, 254 double scaled_sum, 255 std::string* output) const; 256 257 // Retrieves the callback for this histogram, if one exists, and runs it 258 // passing |sample| as the parameter. 259 void FindAndRunCallback(Sample sample) const; 260 261 // Update report with an |activity| that occurred for |histogram|. 262 static void ReportHistogramActivity(const HistogramBase& histogram, 263 ReportActivity activicty); 264 265 // Retrieves the global histogram reporting what histograms are created. 266 static HistogramBase* report_histogram_; 267 268 private: 269 friend class HistogramBaseTest; 270 271 const std::string histogram_name_; 272 AtomicCount flags_; 273 274 DISALLOW_COPY_AND_ASSIGN(HistogramBase); 275 }; 276 277 } // namespace base 278 279 #endif // BASE_METRICS_HISTOGRAM_BASE_H_ 280
