histogram_functions.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265
  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. #ifndef BASE_METRICS_HISTOGRAM_FUNCTIONS_H_
  5. #define BASE_METRICS_HISTOGRAM_FUNCTIONS_H_
  6. #include <string>
  7. #include <type_traits>
  8. #include "base/base_export.h"
  9. #include "base/check_op.h"
  10. #include "base/metrics/histogram.h"
  11. #include "base/metrics/histogram_base.h"
  12. #include "base/time/time.h"
  13. // TODO(crbug/1265443): Update this file's function comments to provide more
  14. // detail, like histogram_macros.h.
  15. //
  16. // Functions for recording metrics.
  17. //
  18. // For best practices on deciding when to emit to a histogram and what form
  19. // the histogram should take, see
  20. // https://chromium.googlesource.com/chromium/src.git/+/HEAD/tools/metrics/histograms/README.md
  21. //
  22. // For deciding whether to use the function or macro APIs, see
  23. // https://chromium.googlesource.com/chromium/src/+/HEAD/tools/metrics/histograms/README.md#coding-emitting-to-histograms"
  24. //
  25. // Every function is duplicated to take both std::string and char* for the name.
  26. // This avoids ctor/dtor instantiation for constant strings to std::string,
  27. // which makes the call be larger than caching macros (which do accept char*)
  28. // in those cases.
  29. namespace base {
  30. // For numeric measurements where you want exact integer values up to
  31. // |exclusive_max|. |exclusive_max| itself is included in the overflow bucket.
  32. // Therefore, if you want an accurate measure up to kMax, then |exclusive_max|
  33. // should be set to kMax + 1.
  34. //
  35. // |exclusive_max| should be 101 or less. If you need to capture a larger range,
  36. // we recommend the use of the COUNT histograms below.
  37. //
  38. // Sample usage:
  39. // base::UmaHistogramExactLinear("Histogram.Linear", sample, kMax + 1);
  40. // In this case, buckets are 1, 2, .., kMax, kMax+1, where the kMax+1 bucket
  41. // captures everything kMax+1 and above.
  42. BASE_EXPORT void UmaHistogramExactLinear(const std::string& name,
  43. int sample,
  44. int exclusive_max);
  45. BASE_EXPORT void UmaHistogramExactLinear(const char* name,
  46. int sample,
  47. int exclusive_max);
  48. // For adding a sample to an enumerated histogram.
  49. // Sample usage:
  50. // // These values are persisted to logs. Entries should not be renumbered and
  51. // // numeric values should never be reused.
  52. // enum class NewTabPageAction {
  53. // kUseOmnibox = 0,
  54. // kClickTitle = 1,
  55. // // kUseSearchbox = 2, // no longer used, combined into omnibox
  56. // kOpenBookmark = 3,
  57. // kMaxValue = kOpenBookmark,
  58. // };
  59. // base::UmaHistogramEnumeration("My.Enumeration",
  60. // NewTabPageAction::kClickTitle);
  61. template <typename T>
  62. void UmaHistogramEnumeration(const std::string& name, T sample) {
  63. static_assert(std::is_enum<T>::value, "T is not an enum.");
  64. // This also ensures that an enumeration that doesn't define kMaxValue fails
  65. // with a semi-useful error ("no member named 'kMaxValue' in ...").
  66. static_assert(static_cast<uintmax_t>(T::kMaxValue) <=
  67. static_cast<uintmax_t>(INT_MAX) - 1,
  68. "Enumeration's kMaxValue is out of range of INT_MAX!");
  69. DCHECK_LE(static_cast<uintmax_t>(sample),
  70. static_cast<uintmax_t>(T::kMaxValue));
  71. return UmaHistogramExactLinear(name, static_cast<int>(sample),
  72. static_cast<int>(T::kMaxValue) + 1);
  73. }
  74. template <typename T>
  75. void UmaHistogramEnumeration(const char* name, T sample) {
  76. static_assert(std::is_enum<T>::value, "T is not an enum.");
  77. // This also ensures that an enumeration that doesn't define kMaxValue fails
  78. // with a semi-useful error ("no member named 'kMaxValue' in ...").
  79. static_assert(static_cast<uintmax_t>(T::kMaxValue) <=
  80. static_cast<uintmax_t>(INT_MAX) - 1,
  81. "Enumeration's kMaxValue is out of range of INT_MAX!");
  82. DCHECK_LE(static_cast<uintmax_t>(sample),
  83. static_cast<uintmax_t>(T::kMaxValue));
  84. return UmaHistogramExactLinear(name, static_cast<int>(sample),
  85. static_cast<int>(T::kMaxValue) + 1);
  86. }
  87. // Some legacy histograms may manually specify the enum size, with a kCount,
  88. // COUNT, kMaxValue, or MAX_VALUE sentinel like so:
  89. // // These values are persisted to logs. Entries should not be renumbered and
  90. // // numeric values should never be reused.
  91. // enum class NewTabPageAction {
  92. // kUseOmnibox = 0,
  93. // kClickTitle = 1,
  94. // // kUseSearchbox = 2, // no longer used, combined into omnibox
  95. // kOpenBookmark = 3,
  96. // kCount,
  97. // };
  98. // base::UmaHistogramEnumeration("My.Enumeration",
  99. // NewTabPageAction::kClickTitle,
  100. // kCount);
  101. // Note: The value in |sample| must be strictly less than |enum_size|. This is
  102. // otherwise functionally equivalent to the above.
  103. template <typename T>
  104. void UmaHistogramEnumeration(const std::string& name, T sample, T enum_size) {
  105. static_assert(std::is_enum<T>::value, "T is not an enum.");
  106. DCHECK_LE(static_cast<uintmax_t>(enum_size), static_cast<uintmax_t>(INT_MAX));
  107. DCHECK_LT(static_cast<uintmax_t>(sample), static_cast<uintmax_t>(enum_size));
  108. return UmaHistogramExactLinear(name, static_cast<int>(sample),
  109. static_cast<int>(enum_size));
  110. }
  111. template <typename T>
  112. void UmaHistogramEnumeration(const char* name, T sample, T enum_size) {
  113. static_assert(std::is_enum<T>::value, "T is not an enum.");
  114. DCHECK_LE(static_cast<uintmax_t>(enum_size), static_cast<uintmax_t>(INT_MAX));
  115. DCHECK_LT(static_cast<uintmax_t>(sample), static_cast<uintmax_t>(enum_size));
  116. return UmaHistogramExactLinear(name, static_cast<int>(sample),
  117. static_cast<int>(enum_size));
  118. }
  119. // For adding boolean sample to histogram.
  120. // Sample usage:
  121. // base::UmaHistogramBoolean("My.Boolean", true)
  122. BASE_EXPORT void UmaHistogramBoolean(const std::string& name, bool sample);
  123. BASE_EXPORT void UmaHistogramBoolean(const char* name, bool sample);
  124. // For adding histogram sample denoting a percentage.
  125. // Percents are integers between 1 and 100, inclusively.
  126. // Sample usage:
  127. // base::UmaHistogramPercentage("My.Percent", 69)
  128. BASE_EXPORT void UmaHistogramPercentage(const std::string& name, int percent);
  129. BASE_EXPORT void UmaHistogramPercentage(const char* name, int percent);
  130. // Obsolete. Use |UmaHistogramPercentage| instead. See crbug/1121318.
  131. BASE_EXPORT void UmaHistogramPercentageObsoleteDoNotUse(const std::string& name,
  132. int percent);
  133. BASE_EXPORT void UmaHistogramPercentageObsoleteDoNotUse(const char* name,
  134. int percent);
  135. // For adding counts histogram.
  136. // Sample usage:
  137. // base::UmaHistogramCustomCounts("My.Counts", some_value, 1, 600, 30)
  138. BASE_EXPORT void UmaHistogramCustomCounts(const std::string& name,
  139. int sample,
  140. int min,
  141. int exclusive_max,
  142. size_t buckets);
  143. BASE_EXPORT void UmaHistogramCustomCounts(const char* name,
  144. int sample,
  145. int min,
  146. int exclusive_max,
  147. size_t buckets);
  148. // Counts specialization for maximum counts 100, 1000, 10k, 100k, 1M and 10M.
  149. BASE_EXPORT void UmaHistogramCounts100(const std::string& name, int sample);
  150. BASE_EXPORT void UmaHistogramCounts100(const char* name, int sample);
  151. BASE_EXPORT void UmaHistogramCounts1000(const std::string& name, int sample);
  152. BASE_EXPORT void UmaHistogramCounts1000(const char* name, int sample);
  153. BASE_EXPORT void UmaHistogramCounts10000(const std::string& name, int sample);
  154. BASE_EXPORT void UmaHistogramCounts10000(const char* name, int sample);
  155. BASE_EXPORT void UmaHistogramCounts100000(const std::string& name, int sample);
  156. BASE_EXPORT void UmaHistogramCounts100000(const char* name, int sample);
  157. BASE_EXPORT void UmaHistogramCounts1M(const std::string& name, int sample);
  158. BASE_EXPORT void UmaHistogramCounts1M(const char* name, int sample);
  159. BASE_EXPORT void UmaHistogramCounts10M(const std::string& name, int sample);
  160. BASE_EXPORT void UmaHistogramCounts10M(const char* name, int sample);
  161. // For histograms storing times. It uses milliseconds granularity.
  162. BASE_EXPORT void UmaHistogramCustomTimes(const std::string& name,
  163. TimeDelta sample,
  164. TimeDelta min,
  165. TimeDelta max,
  166. size_t buckets);
  167. BASE_EXPORT void UmaHistogramCustomTimes(const char* name,
  168. TimeDelta sample,
  169. TimeDelta min,
  170. TimeDelta max,
  171. size_t buckets);
  172. // For short timings from 1 ms up to 10 seconds (50 buckets).
  173. BASE_EXPORT void UmaHistogramTimes(const std::string& name, TimeDelta sample);
  174. BASE_EXPORT void UmaHistogramTimes(const char* name, TimeDelta sample);
  175. // For medium timings up to 3 minutes (50 buckets).
  176. BASE_EXPORT void UmaHistogramMediumTimes(const std::string& name,
  177. TimeDelta sample);
  178. BASE_EXPORT void UmaHistogramMediumTimes(const char* name, TimeDelta sample);
  179. // For time intervals up to 1 hr (50 buckets).
  180. BASE_EXPORT void UmaHistogramLongTimes(const std::string& name,
  181. TimeDelta sample);
  182. BASE_EXPORT void UmaHistogramLongTimes(const char* name, TimeDelta sample);
  183. // For time intervals up to 1 hr (100 buckets).
  184. BASE_EXPORT void UmaHistogramLongTimes100(const std::string& name,
  185. TimeDelta sample);
  186. BASE_EXPORT void UmaHistogramLongTimes100(const char* name, TimeDelta sample);
  187. // For histograms storing times with microseconds granularity.
  188. BASE_EXPORT void UmaHistogramCustomMicrosecondsTimes(const std::string& name,
  189. TimeDelta sample,
  190. TimeDelta min,
  191. TimeDelta max,
  192. size_t buckets);
  193. BASE_EXPORT void UmaHistogramCustomMicrosecondsTimes(const char* name,
  194. TimeDelta sample,
  195. TimeDelta min,
  196. TimeDelta max,
  197. size_t buckets);
  198. // For microseconds timings from 1 microsecond up to 10 seconds (50 buckets).
  199. BASE_EXPORT void UmaHistogramMicrosecondsTimes(const std::string& name,
  200. TimeDelta sample);
  201. BASE_EXPORT void UmaHistogramMicrosecondsTimes(const char* name,
  202. TimeDelta sample);
  203. // For recording memory related histograms.
  204. // Used to measure common KB-granularity memory stats. Range is up to 500M.
  205. BASE_EXPORT void UmaHistogramMemoryKB(const std::string& name, int sample);
  206. BASE_EXPORT void UmaHistogramMemoryKB(const char* name, int sample);
  207. // Used to measure common MB-granularity memory stats. Range is up to ~1G.
  208. BASE_EXPORT void UmaHistogramMemoryMB(const std::string& name, int sample);
  209. BASE_EXPORT void UmaHistogramMemoryMB(const char* name, int sample);
  210. // Used to measure common MB-granularity memory stats. Range is up to ~64G.
  211. BASE_EXPORT void UmaHistogramMemoryLargeMB(const std::string& name, int sample);
  212. BASE_EXPORT void UmaHistogramMemoryLargeMB(const char* name, int sample);
  213. // For recording sparse histograms.
  214. // The |sample| can be a negative or non-negative number.
  215. //
  216. // Sparse histograms are well suited for recording counts of exact sample values
  217. // that are sparsely distributed over a relatively large range, in cases where
  218. // ultra-fast performance is not critical. For instance, Sqlite.Version.* are
  219. // sparse because for any given database, there's going to be exactly one
  220. // version logged.
  221. //
  222. // Performance:
  223. // ------------
  224. // Sparse histograms are typically more memory-efficient but less time-efficient
  225. // than other histograms. Essentially, they sparse histograms use a map rather
  226. // than a vector for their backing storage; they also require lock acquisition
  227. // to increment a sample, whereas other histogram do not. Hence, each increment
  228. // operation is a bit slower than for other histograms. But, if the data is
  229. // sparse, then they use less memory client-side, because they allocate buckets
  230. // on demand rather than preallocating.
  231. //
  232. // Data size:
  233. // ----------
  234. // Note that server-side, we still need to load all buckets, across all users,
  235. // at once. Thus, please avoid exploding such histograms, i.e. uploading many
  236. // many distinct values to the server (across all users). Concretely, keep the
  237. // number of distinct values <= 100 ideally, definitely <= 1000. If you have no
  238. // guarantees on the range of your data, use clamping, e.g.:
  239. // UmaHistogramSparse("My.Histogram", base::clamp(value, 0, 200));
  240. BASE_EXPORT void UmaHistogramSparse(const std::string& name, int sample);
  241. BASE_EXPORT void UmaHistogramSparse(const char* name, int sample);
  242. } // namespace base
  243. #endif // BASE_METRICS_HISTOGRAM_FUNCTIONS_H_