[UMA] Expand the comment for UMA_HISTOGRAM_SPARSE_SLOWLY

base/metrics/histogram_macros.h

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_METRICS_HISTOGRAM_MACROS_H_
 #define BASE_METRICS_HISTOGRAM_MACROS_H_
 
 #include "base/metrics/histogram.h"
 #include "base/metrics/histogram_macros_internal.h"
 #include "base/metrics/histogram_macros_local.h"
@@ skipping 229 matching lines @@
         base::HistogramBase::kUmaStabilityHistogramFlag)
 
 //------------------------------------------------------------------------------
 // Sparse histograms.
 
 // Sparse histograms are well suited for recording counts of exact sample values
 // that are sparsely distributed over a large range.
 //
 // UMA_HISTOGRAM_SPARSE_SLOWLY is good for sparsely distributed and/or
 // infrequently recorded values since the implementation is slower
-// and takes more memory.
+// and takes more memory. For sparse data, sparse histograms have the advantage
+// of using less memory client-side, because they allocate buckets on demand
+// rather than preallocating. However, server-side, we still need to load all
+// buckets, across all users, at once. Thus, please avoid exploding such
+// histograms, i.e. uploading many many distinct values to the server (across

[jkrcal, 2017/04/19 07:58:06]

Maybe we can make the "many many" more concrete. Roughly how many is "many many"
in this context?

[Ilya Sherman, 2017/04/19 17:22:07]

<= 100 is best, and <= 1000 is okay (but more expensive, and overkill in many
cases).

[jkrcal, 2017/04/26 07:39:14]

Done.

+// all users).
 //
 // For instance, Sqlite.Version.* are sparse because for any given database,
 // there's going to be exactly one version logged.
 // The |sample| can be a negative or non-negative number.
 #define UMA_HISTOGRAM_SPARSE_SLOWLY(name, sample)                              \
     INTERNAL_HISTOGRAM_SPARSE_SLOWLY(name, sample)
 
 //------------------------------------------------------------------------------
 // Histogram instantiation helpers.
 
@@ skipping 45 matching lines @@
 // |custom_ranges|. See comments above CustomRanges::FactoryGet about the
 // requirement of |custom_ranges|. You can use the helper function
 // CustomHistogram::ArrayToCustomRanges to transform a C-style array of valid
 // sample values to a std::vector<int>.
 #define UMA_HISTOGRAM_CUSTOM_ENUMERATION(name, sample, custom_ranges)          \
     STATIC_HISTOGRAM_POINTER_BLOCK(name, Add(sample),                          \
         base::CustomHistogram::FactoryGet(name, custom_ranges,                 \
             base::HistogramBase::kUmaTargetedHistogramFlag))
 
 #endif  // BASE_METRICS_HISTOGRAM_MACROS_H_