Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(1)

Side by Side Diff: tools/metrics/histograms/README.md

Issue 2381233002: Metrics - Add histograms/README.md (Closed)
Patch Set: Created 4 years, 2 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
1 # Histogram Guidelines
rkaplow 2016/09/30 17:12:02 You could put the pointer to this file from histog
Mark P 2016/09/30 22:40:36 Done for both.
2
3 This document gives the best practices on how to use histograms in code and how
4 to document the histograms for the dashboard. There are three general types of
5 histograms: enumerated histograms (appropriate for enums), count histograms
6 (appropriate for arbitrary numbers), and sparse histogram (appropriate for
7 anything when the precision is important over a wide range is large and/or the
8 range is not possible to specify a priori).
9
10 [TOC]
11
12 ## Emitting to Histograms
13
14 ### Efficiency
15
16 In general, the histogram code is highly optimized. Do not be concerned about
17 the processing cost of emitting to a histogram (unless you're using [sparse
18 histograms](#when-to-use-sparse-histograms)).
19
20 ### Enum Histograms
21
22 Enumerated histogram are most appropriate when you have a list of connected /
23 related states that should be analyzed jointly. For example, the set of
24 actions that can be done on the New Tab Page (use the omnibox, click a most
25 visited tile, click a bookmark, etc.) would make a good enumerated histogram.
rkaplow 2016/09/30 17:12:01 you may also want to add something like: "It is o
Mark P 2016/09/30 22:40:36 Added a less wordy version. :-) Thanks for the f
26
27 Please put a warning by the enum definition:
28 ```
29 // These values are written to logs. New enum values can be added, but existing
30 // enums must never be renumbered or deleted and reused.
31 ```
32
33 Also, please explicitly set enum values `= 0`, `= 1`, `= 2`, etc. This makes
rkaplow 2016/09/30 17:12:02 Probably worth mentioning that we allow appending
Mark P 2016/09/30 22:40:36 Done.
34 clearer that the actual values are important. In addition, it helps confirm
35 the values align between the enum definition and histograms.xml.
36
37 ### Count Histograms: Choosing Min and Max
rkaplow 2016/09/30 17:12:01 should we have a small introduction to counts here
Mark P 2016/09/30 22:40:36 Done. Seems a little wordy though. :-| *shrug*
38
39 For histogram max, choose a value so that very few emission to the histogram
40 will exceed the max. If many emissions hit the max, it can be difficult to
41 compute statistics such as average or high order percentiles such as the 99th
42 percentile. Err on the side of too large a range versus too short a range.
rkaplow 2016/09/30 17:12:02 Also option, you can put something like: "One rul
Mark P 2016/09/30 22:40:36 Added, and removed an existing clause. Then added
43
44 For histogram min, if you care about all possible values (zero and above),
45 choose a min of 1. (All histograms have an underflow bucket; emitted zeros
46 will go there. That's why a min of 1 is appropriate.) Otherwise, choose the
47 min appropriate for your particular situation.
48
49 ### Count Histograms: Choosing Number of Buckets
50
51 Choose the smallest number of buckets that will get you the granularity you
52 need. By default count histograms bucket sizes scale exponentially so you can
53 get finely granularity when the numbers are small yet still reasonable
54 resolution for larger numbers. The macros default to bucket sizes around 50
55 which is appropriate for most purposes. Because histograms pre-allocate all
56 the buckets, the number of buckets selected directly dictate how much memory
57 is used. Do not exceed 100 buckets without good reason (and consider whether
58 [sparse histograms](#when-to-use-sparse-histograms) might work better for you
59 in that case--they do not pre-allocate their buckets).
60
61 ### Count Histograms with Linear Ranges
62
63 If you want equally spaced buckets of size 1, use an enumerated histogram.
64 While it's possible to do this with a count histogram, it's easy to make a
65 mistake when setting the min, max, and number of buckets (because you have
66 to remember how underflow and overflow buckets are handled) and end up with
67 a histogram that ends up with mostly buckets of size 1 but not all.
68 Using an enumerated histogram with a max value of your own choice is less
69 error-prone.
70
71 ### Testing
72
73 Test your histograms using [chrome://histograms](chrome://histograms). Make
74 sure they're being emitted to when you expect and not emitted to at other times.
75 Also check that the values emitted to are correct. Finally, for count
76 histograms, make sure that buckets capture enough precision for your needs over
77 the range.
78
79 ### Revising Histograms
80
81 If you're changing the semantics of a histogram (when it's emitted, what buckets
82 mean, etc.), make it into a new histogram with a new name. Otherwise the
83 "Everything" view on the dashboard will be mixing two different interpretations
84 of the data and make no sense.
85
86 ### Deleting Histograms
87
88 Please delete the code that emits to histograms that are no longer needed.
89 Histograms take up memory. Cleaning up histograms that you no longer care aboud
90 is good! But see the note below on [Deleting Histogram Entries]
91 (#deleting-histogram-entries).
92
93 ## Documenting Histograms
94
95 ### Add Histogram and Documentation in the Same Changelist
96
97 If possible, please add the histograms.xml description in the same changelist
98 in which you add the histogram-emitting code. This has several benefits. One,
99 it sometimes happens that the histograms.xml reviewer has questions or concerns
100 about the histogram description that reveal problems with interpretation of the
101 data and call for a different recording strategy. Two, it allows the histogram
102 reviewer to easily review the emission code to see if it comports with these
103 best practices, and to look for other errors.
104
105 ### Understandable to Everyone
106
107 Histogram descriptions should be roughly understandable to someone not familiar
108 with with your feature. Please add a sentence or two of background if
109 necessary.
rkaplow 2016/09/30 17:12:01 Maybe add: It is good practice to note caveats as
Mark P 2016/09/30 22:40:36 I don't think the list of platforms should be adde
110
111 ### State When It Is Recorded
112
113 Histogram descriptions should clearly state when the histogram is emitted
114 (profile open? network request received? etc.).
115
116 ### Deleting Histogram Entries
117
118 Do not delete histograms from histograms.xml. Instead, mark unused histograms
119 as obsolete. It would be bad if someone to accidentally reused your old
rkaplow 2016/09/30 17:12:02 obsolete, with the associated date or milestone in
Mark P 2016/09/30 22:40:36 Both good suggestions. Integrated them both.
120 histogram name and thereby corrupts new data with whatever old data is still
121 coming in. It's also useful to keep obsolete histogram descriptions in
122 histograms.xml--that way, if someone is searching for a histogram to answer
123 a particular question, they can learn if there was a histogram at some point
124 that did so even if it isn't active now.
125
126 ## When To Use Sparse Histograms
127
128 Sparse histograms are well suited for recording counts of exact sample values
129 that are sparsely distributed over a large range.
130
131 The implementation uses a lock and a map, whereas other histogram types use a
132 vector and no lock. It is thus more costly to add values to, and each value
133 stored has more overhead, compared to the other histogram types. However it
134 may be more efficient in memory if the total number of sample values is small
135 compared to the range of their values.
136
137 For more information, see [sparse_histograms.h]
138 (https://cs.chromium.org/chromium/src/base/metrics/sparse_histogram.h).
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698