Commit 9be8bffa authored by Mark Pearson's avatar Mark Pearson Committed by Commit Bot

Histograms README - Clarify Percentage Histogram Advice

The previous advice was too strict about emitting at a regular
interval when at the end of event is perfectly okay.

Inspired by
https://chromium-review.googlesource.com/c/chromium/src/+/2049824/16

Change-Id: I93b3f44a9c91d623e08c9327d902e7ca6af36263
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/2083683
Commit-Queue: Mark Pearson <mpearson@chromium.org>
Reviewed-by: default avatarIlya Sherman <isherman@chromium.org>
Cr-Commit-Position: refs/heads/master@{#746464}
parent e37525e7
...@@ -261,16 +261,20 @@ UMA_HISTOGRAM_PERCENTAGE macro provided in ...@@ -261,16 +261,20 @@ UMA_HISTOGRAM_PERCENTAGE macro provided in
You can also easily emit any ratio as a linear histogram (for equally You can also easily emit any ratio as a linear histogram (for equally
sized buckets). sized buckets).
For such histograms, you should think carefully about _when_ the values are For such histograms, you want each value recorded to cover approximately
emitted. Normally, you should emit values periodically at a set time interval, the same span of time. This typically means emitting values periodically
such as every 5 minutes. Conversely, we strongly discourage emitting values at a set time interval, such as every 5 minutes. We do not recommend
based on event triggers. For example, we do not recommend recording a ratio recording a ratio at the end of a video playback, as lengths of videos
at the end of a video playback. vary greatly.
Why? You typically cannot make decisions based on histograms whose values are It is okay to emit at the end of an animation sequence when what's being
recorded in response to an event, because such metrics can conflate heavy usage animated is fixed / known. In this case, each value will represent
with light usage. It's easier to reason about metrics that route around this roughly the same span of time.
source of bias.
Why? You typically cannot make decisions based on histograms whose
values are recorded in response to an event that varies in length,
because such metrics can conflate heavy usage with light usage. It's
easier to reason about metrics that route around this source of bias.
Many developers have been bitten by this. For example, it was previously common Many developers have been bitten by this. For example, it was previously common
to emit an actions-per-minute ratio whenever Chrome was backgrounded. to emit an actions-per-minute ratio whenever Chrome was backgrounded.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment