Index: tools/metrics/histograms/README.md |
diff --git a/tools/metrics/histograms/README.md b/tools/metrics/histograms/README.md |
index c1efcab6c6771a93e255fb7c0c71eb7f6da4ef12..fa0586d91ea21f3a8bc7d2b6080c995ade0ddc58 100644 |
--- a/tools/metrics/histograms/README.md |
+++ b/tools/metrics/histograms/README.md |
@@ -1,8 +1,8 @@ |
# Histogram Guidelines |
This document gives the best practices on how to use histograms in code and how |
-to document the histograms for the dashboard. There are three general types of |
-histograms: enumerated histograms (appropriate for enums), count histograms |
+to document the histograms for the dashboards. There are three general types |
+of histograms: enumerated histograms (appropriate for enums), count histograms |
(appropriate for arbitrary numbers), and sparse histogram (appropriate for |
anything when the precision is important over a wide range is large and/or the |
range is not possible to specify a priori). |
@@ -31,7 +31,7 @@ care about; don't try to derive it from other data. |
In general, the histogram code is highly optimized. Do not be concerned about |
the processing cost of emitting to a histogram (unless you're using [sparse |
-histograms](#when-to-use-sparse-histograms)). |
+histograms](#When-To-Use-Sparse-Histograms)). |
### Enum Histograms |
@@ -67,7 +67,7 @@ will need to choose the histogram max (use the advice below). |
If none of the default macros work well for you, please thoughtfully choose |
a min, max, and bucket count for your histogram using the advice below. |
-### Count Histograms: Choosing Min and Max |
+#### Count Histograms: Choosing Min and Max |
For histogram max, choose a value so that very few emission to the histogram |
will exceed the max. If many emissions hit the max, it can be difficult to |
@@ -80,35 +80,24 @@ choose a min of 1. (All histograms have an underflow bucket; emitted zeros |
will go there. That's why a min of 1 is appropriate.) Otherwise, choose the |
min appropriate for your particular situation. |
-### Count Histograms: Choosing Number of Buckets |
+#### Count Histograms: Choosing Number of Buckets |
Choose the smallest number of buckets that will get you the granularity you |
need. By default count histograms bucket sizes scale exponentially so you can |
-get finely granularity when the numbers are small yet still reasonable |
-resolution for larger numbers. The macros default to bucket sizes around 50 |
-which is appropriate for most purposes. Because histograms pre-allocate all |
-the buckets, the number of buckets selected directly dictate how much memory |
-is used. Do not exceed 100 buckets without good reason (and consider whether |
-[sparse histograms](#when-to-use-sparse-histograms) might work better for you |
-in that case--they do not pre-allocate their buckets). |
- |
-### Count Histograms with Linear Ranges |
- |
-If you want equally spaced buckets of size 1, use an enumerated histogram. |
-While it's possible to do this with a count histogram, it's easy to make a |
-mistake when setting the min, max, and number of buckets (because you have |
-to remember how underflow and overflow buckets are handled) and end up with |
-a histogram that ends up with mostly buckets of size 1 but not all. |
-Using an enumerated histogram with a max value of your own choice is less |
-error-prone. |
+get fine granularity when the numbers are small yet still reasonable resolution |
+for larger numbers. The macros default to 50 (or 100 for large) buckets which |
+is appropriate for most purposes. Because histograms pre-allocate all the |
+buckets, the number of buckets selected directly dictate how much memory is |
+used. Do not exceed 100 buckets without good reason (and consider whether |
+[sparse histograms](#When-To-Use-Sparse-Histograms) might work better for you |
+in that case--they do not pre- allocate their buckets). |
### Testing |
-Test your histograms using [chrome://histograms](chrome://histograms). Make |
-sure they're being emitted to when you expect and not emitted to at other times. |
-Also check that the values emitted to are correct. Finally, for count |
-histograms, make sure that buckets capture enough precision for your needs over |
-the range. |
+Test your histograms using *chrome://histograms*. Make sure they're being |
+emitted to when you expect and not emitted to at other times. Also check that |
+the values emitted to are correct. Finally, for count histograms, make sure |
+that buckets capture enough precision for your needs over the range. |
### Revising Histograms |
@@ -121,8 +110,7 @@ of the data and make no sense. |
Please delete the code that emits to histograms that are no longer needed. |
Histograms take up memory. Cleaning up histograms that you no longer care about |
-is good! But see the note below on [Deleting Histogram Entries] |
-(#deleting-histogram-entries). |
+is good! But see the note below on [Deleting Histogram Entries](#Deleting-Histogram-Entries). |
## Documenting Histograms |
@@ -176,5 +164,4 @@ stored has more overhead, compared to the other histogram types. However it |
may be more efficient in memory if the total number of sample values is small |
compared to the range of their values. |
-For more information, see [sparse_histograms.h] |
-(https://cs.chromium.org/chromium/src/base/metrics/sparse_histogram.h). |
+For more information, see [sparse_histograms.h](https://cs.chromium.org/chromium/src/base/metrics/sparse_histogram.h). |