Bug 1540708 Clarify some of the Origin Telemetry docs. r=janerik
authorChris H-C <chutten@mozilla.com>
Wed, 03 Apr 2019 09:47:34 +0000
changeset 467793 22f56decf8fa9a808461a46570559e03cb7a53ed
parent 467792 dbb61d5c5944a9394e87244dace7ebfd5b0b0801
child 467794 3bed147b65d6e88a81056d593a8e9ba916d9f568
push id82210
push userchutten@mozilla.com
push dateWed, 03 Apr 2019 15:35:32 +0000
treeherderautoland@22f56decf8fa [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersjanerik
bugs1540708
milestone68.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1540708 Clarify some of the Origin Telemetry docs. r=janerik Differential Revision: https://phabricator.services.mozilla.com/D25822
toolkit/components/telemetry/docs/collection/origin.rst
toolkit/components/telemetry/docs/data/prio-ping.rst
--- a/toolkit/components/telemetry/docs/collection/origin.rst
+++ b/toolkit/components/telemetry/docs/collection/origin.rst
@@ -43,16 +43,20 @@ 2. The metric must be one of the fixed, 
 3. A call must be made to the Origin Telemetry API. (To let Origin Telemetry know "that" happened "there")
 
 At present the lists of origins and metrics are hardcoded in C++.
 Please consult the Firefox Telemetry Team before changing these lists.
 
 Origins can be arbitrary byte sequences of any length.
 Do not add duplicate origins to the list.
 
+If an attempt is made to record to an unknown origin, a meta-origin ``__UNKNOWN__`` captures that it happened.
+Unlike other origins where multiple recordings are considered additive ``__UNKNOWN__`` only accumulates a single value.
+This is to avoid inflating the ping size in case the caller submits a lot of unknown origins for a given unit (e.g. pageload).
+
 Metrics should be of the form ``categoryname.metric_name``.
 Both ``categoryname`` and ``metric_name`` should not exceed 40 bytes (UTF-8 encoded) in length and should only contain alphanumeric character and infix underscores.
 
 .. _origin.API:
 
 API
 ===
 
--- a/toolkit/components/telemetry/docs/data/prio-ping.rst
+++ b/toolkit/components/telemetry/docs/data/prio-ping.rst
@@ -42,16 +42,19 @@ The ``reason`` field contains the inform
 * ``periodic``: The ping was submitted because some Origin Telemetry was recorded in the past day.
 * ``max``: The ping was submitted because the 10-element limit was reached.
 * ``shutdown``: The ping was submitted because Firefox is shutting down and some Origin Telemetry data have yet to be submitted.
 
 prioData
 ~~~~~~~~
 An array of ``encoding``/``prio`` pairs.
 
+Multiple elements of the ``prioData`` array may have the same ``encoding``.
+This is how we encode how many times something happened.
+
 .. _prio-ping.encoding:
 
 encoding
 ~~~~~~~~
 The name of the encoding process used to encode the payload.
 In short: This field identifies how :ref:`Origin Telemetry <origintelemetry>` encoded information of the form "tracker 'example.net' was blocked" into a boolean, split it into small enough lists for Prio to encode, encrypted it with a Prio batch ID, and did all the rest of the stuff it needed to do in order for it to be sent.
 This name enables the servers to be able to make sense of the base64 strings we're sending it so we can get the aggregated information out on the other end.