From c2bf95fd8be2848d343cea52474bfe960499ba1d Mon Sep 17 00:00:00 2001
From: Darin Petkov <petkov@chromium.org>
Date: Mon, 21 Jun 2010 16:27:52 -0700
Subject: [PATCH] Update libmetrics docs to cover some recent questions and
 issues.

Review URL: http://codereview.chromium.org/2828017
---
 metrics/README            | 33 +++++++++++++++++++++++++++++++++
 metrics/metrics_library.h | 11 +++++++++++
 2 files changed, 44 insertions(+)

diff --git a/metrics/README b/metrics/README
index 42193796e..677e6b75c 100644
--- a/metrics/README
+++ b/metrics/README
@@ -116,3 +116,36 @@ signals to or communicate in some alternative way with the metrics
 daemon. Then the metrics daemon needs to monitor for the relevant
 events and take appropriate action -- for example, aggregate data and
 send the histogram samples.
+
+
+================================================================================
+FAQ
+================================================================================
+
+Q. What should my histogram's |min| and |max| values be set at?
+
+A. You should set the values to a range that covers the vast majority
+   of samples that would appear in the field. Note that samples below
+   the |min| will still be collected in the underflow bucket and
+   samples above the |max| will end up in the overflow bucket. Also,
+   the reported mean of the data will be correct regardless of the
+   range.
+
+Q. How many buckets should I use in my histogram?
+
+A. You should allocate as many buckets as necessary to perform proper
+   analysis on the collected data. Note, however, that the memory
+   allocated in Chrome for each histogram is proportional to the
+   number of buckets. Therefore, it is strongly recommended to keep
+   this number low (e.g., 50 is normal, while 100 is probably high).
+
+Q. When should I use an enumeration (linear) histogram vs. a regular
+   (exponential) histogram?
+
+A. Enumeration histograms should really be used only for sampling
+   enumerated events and, in some cases, percentages. Normally, you
+   should use a regular histogram with exponential bucket layout that
+   provides higher resolution at the low end of the range and lower
+   resolution at the high end. Regular histograms are generally used
+   for collecting performance data (e.g., timing, memory usage, power)
+   as well as aggregated event counts.
diff --git a/metrics/metrics_library.h b/metrics/metrics_library.h
index 80bea70a3..76fa451ea 100644
--- a/metrics/metrics_library.h
+++ b/metrics/metrics_library.h
@@ -38,6 +38,11 @@ class MetricsLibrary : public MetricsLibraryInterface {
   // |nbuckets| is the number of histogram buckets.
   // [0,min) is the implicit underflow bucket.
   // [|max|,infinity) is the implicit overflow bucket.
+  //
+  // Note that the memory allocated in Chrome for each histogram is
+  // proportional to the number of buckets. Therefore, it is strongly
+  // recommended to keep this number low (e.g., 50 is normal, while
+  // 100 is high).
   bool SendToUMA(const std::string& name, int sample,
                  int min, int max, int nbuckets);
 
@@ -50,6 +55,12 @@ class MetricsLibrary : public MetricsLibraryInterface {
   // |max| is the maximum value of the histogram samples.
   // 0 is the implicit underflow bucket.
   // [|max|,infinity) is the implicit overflow bucket.
+  //
+  // An enumaration histogram requires |max| + 1 number of
+  // buckets. Note that the memory allocated in Chrome for each
+  // histogram is proportional to the number of buckets. Therefore, it
+  // is strongly recommended to keep this number low (e.g., 50 is
+  // normal, while 100 is high).
   bool SendEnumToUMA(const std::string& name, int sample, int max);
 
   // Sends to Autotest and returns true on success.