1 // Copyright 2016 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_FUNCTIONS_H_
6 #define BASE_METRICS_HISTOGRAM_FUNCTIONS_H_
7
8 #include "base/metrics/histogram.h"
9 #include "base/metrics/histogram_base.h"
10 #include "base/time/time.h"
11
12 // Functions for recording metrics.
13 //
14 // For best practices on deciding when to emit to a histogram and what form
15 // the histogram should take, see
16 // https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/histograms/README.md
17
18 // Functions for recording UMA histograms. These can be used for cases
19 // when the histogram name is generated at runtime. The functionality is
20 // equivalent to macros defined in histogram_macros.h but allowing non-constant
21 // histogram names. These functions are slower compared to their macro
22 // equivalent because the histogram objects are not cached between calls.
23 // So, these shouldn't be used in performance critical code.
24 namespace base {
25
26 // For histograms with linear buckets.
27 // Used for capturing integer data with a linear bucketing scheme. This can be
28 // used when you want the exact value of some small numeric count, with a max of
29 // 100 or less. If you need to capture a range of greater than 100, we recommend
30 // the use of the COUNT histograms below.
31 // Sample usage:
32 // base::UmaHistogramExactLinear("Histogram.Linear", some_value, 10);
33 BASE_EXPORT void UmaHistogramExactLinear(const std::string& name,
34 int sample,
35 int value_max);
36
37 // For adding a sample to an enumerated histogram.
38 // Sample usage:
39 // // These values are persisted to logs. Entries should not be renumbered and
40 // // numeric values should never be reused.
41 // enum class MyEnum {
42 // FIRST_VALUE = 0,
43 // SECOND_VALUE = 1,
44 // ...
45 // FINAL_VALUE = N,
46 // COUNT
47 // };
48 // base::UmaHistogramEnumeration("My.Enumeration",
49 // MyEnum::SOME_VALUE, MyEnum::COUNT);
50 //
51 // Note: The value in |sample| must be strictly less than |enum_size|.
52 template <typename T>
UmaHistogramEnumeration(const std::string & name,T sample,T enum_size)53 void UmaHistogramEnumeration(const std::string& name, T sample, T enum_size) {
54 static_assert(std::is_enum<T>::value,
55 "Non enum passed to UmaHistogramEnumeration");
56 DCHECK_LE(static_cast<uintmax_t>(enum_size), static_cast<uintmax_t>(INT_MAX));
57 DCHECK_LT(static_cast<uintmax_t>(sample), static_cast<uintmax_t>(enum_size));
58 return UmaHistogramExactLinear(name, static_cast<int>(sample),
59 static_cast<int>(enum_size));
60 }
61
62 // Same as above, but uses T::kMaxValue as the inclusive maximum value of the
63 // enum.
64 template <typename T>
UmaHistogramEnumeration(const std::string & name,T sample)65 void UmaHistogramEnumeration(const std::string& name, T sample) {
66 static_assert(std::is_enum<T>::value,
67 "Non enum passed to UmaHistogramEnumeration");
68 DCHECK_LE(static_cast<uintmax_t>(T::kMaxValue),
69 static_cast<uintmax_t>(INT_MAX) - 1);
70 DCHECK_LE(static_cast<uintmax_t>(sample),
71 static_cast<uintmax_t>(T::kMaxValue));
72 return UmaHistogramExactLinear(name, static_cast<int>(sample),
73 static_cast<int>(T::kMaxValue) + 1);
74 }
75
76 // For adding boolean sample to histogram.
77 // Sample usage:
78 // base::UmaHistogramBoolean("My.Boolean", true)
79 BASE_EXPORT void UmaHistogramBoolean(const std::string& name, bool sample);
80
81 // For adding histogram with percent.
82 // Percents are integer between 1 and 100.
83 // Sample usage:
84 // base::UmaHistogramPercentage("My.Percent", 69)
85 BASE_EXPORT void UmaHistogramPercentage(const std::string& name, int percent);
86
87 // For adding counts histogram.
88 // Sample usage:
89 // base::UmaHistogramCustomCounts("My.Counts", some_value, 1, 600, 30)
90 BASE_EXPORT void UmaHistogramCustomCounts(const std::string& name,
91 int sample,
92 int min,
93 int max,
94 int buckets);
95
96 // Counts specialization for maximum counts 100, 1000, 10k, 100k, 1M and 10M.
97 BASE_EXPORT void UmaHistogramCounts100(const std::string& name, int sample);
98 BASE_EXPORT void UmaHistogramCounts1000(const std::string& name, int sample);
99 BASE_EXPORT void UmaHistogramCounts10000(const std::string& name, int sample);
100 BASE_EXPORT void UmaHistogramCounts100000(const std::string& name, int sample);
101 BASE_EXPORT void UmaHistogramCounts1M(const std::string& name, int sample);
102 BASE_EXPORT void UmaHistogramCounts10M(const std::string& name, int sample);
103
104 // For histograms storing times.
105 BASE_EXPORT void UmaHistogramCustomTimes(const std::string& name,
106 TimeDelta sample,
107 TimeDelta min,
108 TimeDelta max,
109 int buckets);
110 // For short timings from 1 ms up to 10 seconds (50 buckets).
111 BASE_EXPORT void UmaHistogramTimes(const std::string& name, TimeDelta sample);
112 // For medium timings up to 3 minutes (50 buckets).
113 BASE_EXPORT void UmaHistogramMediumTimes(const std::string& name,
114 TimeDelta sample);
115 // For time intervals up to 1 hr (50 buckets).
116 BASE_EXPORT void UmaHistogramLongTimes(const std::string& name,
117 TimeDelta sample);
118
119 // For recording memory related histograms.
120 // Used to measure common KB-granularity memory stats. Range is up to 500M.
121 BASE_EXPORT void UmaHistogramMemoryKB(const std::string& name, int sample);
122 // Used to measure common MB-granularity memory stats. Range is up to ~1G.
123 BASE_EXPORT void UmaHistogramMemoryMB(const std::string& name, int sample);
124 // Used to measure common MB-granularity memory stats. Range is up to ~64G.
125 BASE_EXPORT void UmaHistogramMemoryLargeMB(const std::string& name, int sample);
126
127 // For recording sparse histograms.
128 // The |sample| can be a negative or non-negative number.
129 //
130 // Sparse histograms are well suited for recording counts of exact sample values
131 // that are sparsely distributed over a relatively large range, in cases where
132 // ultra-fast performance is not critical. For instance, Sqlite.Version.* are
133 // sparse because for any given database, there's going to be exactly one
134 // version logged.
135 //
136 // Performance:
137 // ------------
138 // Sparse histograms are typically more memory-efficient but less time-efficient
139 // than other histograms. Essentially, they sparse histograms use a map rather
140 // than a vector for their backing storage; they also require lock acquisition
141 // to increment a sample, whereas other histogram do not. Hence, each increment
142 // operation is a bit slower than for other histograms. But, if the data is
143 // sparse, then they use less memory client-side, because they allocate buckets
144 // on demand rather than preallocating.
145 //
146 // Data size:
147 // ----------
148 // Note that server-side, we still need to load all buckets, across all users,
149 // at once. Thus, please avoid exploding such histograms, i.e. uploading many
150 // many distinct values to the server (across all users). Concretely, keep the
151 // number of distinct values <= 100 ideally, definitely <= 1000. If you have no
152 // guarantees on the range of your data, use clamping, e.g.:
153 // UmaHistogramSparse("MyHistogram", ClampToRange(value, 0, 200));
154 BASE_EXPORT void UmaHistogramSparse(const std::string& name, int sample);
155
156 } // namespace base
157
158 #endif // BASE_METRICS_HISTOGRAM_FUNCTIONS_H_
159