Bug 1413270 - Document how to interpret use counter data. r?chutten draft
authorAlessio Placitelli <alessio.placitelli@gmail.com>
Tue, 21 Nov 2017 14:28:55 +0100
changeset 701779 cb28d24450dd753f977d62ab3b169ea14ec1d9d6
parent 700905 081c06e175b2b4431b7af5ea594ff0373e97b70a
child 741273 1e20878dafeb025eedc4ae0cde6d0e0904d5aee4
push id90278
push useralessio.placitelli@gmail.com
push dateWed, 22 Nov 2017 08:27:12 +0000
reviewerschutten
bugs1413270
milestone59.0a1
Bug 1413270 - Document how to interpret use counter data. r?chutten This patch adds a new section to the use counters Telemetry docs that explains how one should think of the data gathered using them. MozReview-Commit-ID: 5mYIYubWxaz
toolkit/components/telemetry/docs/collection/use-counters.rst
--- a/toolkit/components/telemetry/docs/collection/use-counters.rst
+++ b/toolkit/components/telemetry/docs/collection/use-counters.rst
@@ -73,8 +73,25 @@ The definition files are processed twice
     The histograms that are generated out of use counters are set to *never* expire and are *opt-in*.
 
 gen-usecounters.py
 ------------------
 This script is called by the build system to generate:
 
 - the ``PropertyUseCounterMap.inc`` C++ header for the CSS properties;
 - the ``UseCounterList.h`` header for the WebIDL, out of the definition files.
+
+Interpreting the data
+=====================
+The histogram as accumulated on the client only puts values into the 1 bucket, meaning that
+the use counter directly reports if a feature was used but it does not directly report if
+it isn't used.
+The values accumulated within a use counter should be considered proportional to
+``CONTENT_DOCUMENTS_DESTROYED`` and ``TOP_LEVEL_CONTENT_DOCUMENTS_DESTROYED`` (see
+`here <https://dxr.mozilla.org/mozilla-central/rev/b056526be38e96b3e381b7e90cd8254ad1d96d9d/dom/base/nsDocument.cpp#13209-13231>`__). The difference between the values of these two histograms
+and the related use counters below tell us how many pages did *not* use the feature in question.
+For instance, if we see that a given session has destroyed 30 content documents, but a
+particular use counter shows only a count of 5, we can infer that the use counter was *not*
+used in 25 of those 30 documents.
+
+Things are done this way, rather than accumulating a boolean flag for each use counter,
+to avoid sending histograms for features that don't get widely used. Doing things in this
+fashion means smaller telemetry payloads and faster processing on the server side.