bug 1406394 - Update Telemetry docs for preference changes r=Dexter
authorChris H-C <chutten@mozilla.com>
Thu, 09 Nov 2017 09:38:24 -0500
changeset 436108 a736899d6d3186dacfdd4867e0484ac855486361
parent 436107 b3883358e0182cd158341f62e87f31c3b69f3c5d
child 436109 4d80bc4f0161ae83915e7323eefe49ee39224199
push id117
push userfmarier@mozilla.com
push dateTue, 28 Nov 2017 20:17:16 +0000
reviewersDexter
bugs1406394
milestone59.0a1
bug 1406394 - Update Telemetry docs for preference changes r=Dexter MozReview-Commit-ID: D5Qw2Reuc5o
toolkit/components/telemetry/docs/collection/histograms.rst
toolkit/components/telemetry/docs/collection/scalars.rst
toolkit/components/telemetry/docs/collection/stack-capture.rst
toolkit/components/telemetry/docs/internals/preferences.rst
--- a/toolkit/components/telemetry/docs/collection/histograms.rst
+++ b/toolkit/components/telemetry/docs/collection/histograms.rst
@@ -185,18 +185,18 @@ Required. A description of the data trac
 ``cpp_guard``
 -------------
 Optional. This field inserts an #ifdef directive around the histogram's C++ declaration. This is typically used for platform-specific histograms, e.g. ``"cpp_guard": "ANDROID"``
 
 ``releaseChannelCollection``
 ----------------------------
 Optional. This is one of:
 
-* ``"opt-in"``: (default value) This histogram is submitted by default on pre-release channels; on the release channel only if the user opted into additional data collection
-* ``"opt-out"``: this histogram is submitted by default on release and pre-release channels, unless the user opted out.
+* ``"opt-in"``: (default value) This histogram is submitted by default on pre-release channels, unless the user opts out.
+* ``"opt-out"``: This histogram is submitted by default on release and pre-release channels, unless the user opts out.
 
 .. warning::
 
     Because they are collected by default, opt-out probes need to meet a higher "user benefit" threshold than opt-in probes during data collection review.
 
 
     **Every** new data collection in Firefox needs a `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection#Requesting_Approval>`_ from a data collection peer. Just set the feedback? flag for one of the data peers.
 
--- a/toolkit/components/telemetry/docs/collection/scalars.rst
+++ b/toolkit/components/telemetry/docs/collection/scalars.rst
@@ -159,17 +159,17 @@ Required Fields
   - ``gpu``;
   - ``all_child`` (record in all the child processes);
   - ``all`` (record in all the processes).
 
 Optional Fields
 ---------------
 
 - ``cpp_guard``: A string that gets inserted as an ``#ifdef`` directive around the automatically generated C++ declaration. This is typically used for platform-specific scalars, e.g. ``ANDROID``.
-- ``release_channel_collection``: This can be either ``opt-in`` (default) or ``opt-out``. With the former the scalar is submitted by default on pre-release channels; on the release channel only if the user opted into additional data collection. With the latter the scalar is submitted by default on release and pre-release channels, unless the user opted out.
+- ``release_channel_collection``: This can be either ``opt-in`` (default) or ``opt-out``. With the former the scalar is submitted by default on pre-release channels, unless the user has opted out. With the latter the scalar is submitted by default on release and pre-release channels, unless the user has opted out.
 - ``keyed``: A boolean that determines whether this is a keyed scalar. It defaults to ``False``.
 
 String type restrictions
 ------------------------
 To prevent abuses, the content of a string scalar is limited to 50 characters in length. Trying
 to set a longer string will result in an error and no string being set.
 
 Keyed Scalars
@@ -242,17 +242,17 @@ Let's start by registering two probes in
         keyed: true
         notification_emails:
           - change-me@allizom.com
         release_channel_collection: opt-in
         record_in_processes:
           - 'main'
 
 These two scalars have different collection policies and are both constrained to recording only in the main process.
-For example, the ``ui.download_button_activated`` can be recorded only by users who opted into the extended Telemetry collection.
+For example, the ``ui.download_button_activated`` can be recorded only by users on running pre-release builds of Firefox.
 
 Using the JS API
 ----------------
 Changing the demo scalars from privileged JavaScript code is straightforward:
 
 .. code-block:: js
 
   // Set the scalar value: trying to use a non-boolean value doesn't throw
--- a/toolkit/components/telemetry/docs/collection/stack-capture.rst
+++ b/toolkit/components/telemetry/docs/collection/stack-capture.rst
@@ -4,18 +4,17 @@ Stack capture
 
 While studying behavior of Firefox in the wild it is sometimes useful to inspect
 call stacks without causing the browser to crash. Historically we could only
 obtain stacks for inspection from crash reports. Now stacks can be captured on
 demand and annotated with a unique key for further inspection.
 
 Capturing stacks is only supported on official builds with ``--enable-profiling``
 switch enabled, such as Nightly builds, for example. The feature is available on
-Windows, Linux and macOS. Capturing stacks is only available with extended Telemetry
-enabled.
+Windows, Linux and macOS builds of Firefox.
 
 Captured stacks are grouped by a user-defined key. Identical stacks captured under
 the same key are combined in order to reduce their memory footprint. A counter is
 used to reflect the frequency of identical stacks.
 
 The serialized stack data is submitted with the :doc:`main pings <../data/main-ping>`.
 
 The API
--- a/toolkit/components/telemetry/docs/internals/preferences.rst
+++ b/toolkit/components/telemetry/docs/internals/preferences.rst
@@ -82,29 +82,27 @@ Preferences
 
 ``toolkit.telemetry.unified``
 
   This controls whether unified behavior is enabled. If true:
 
   * Telemetry is always enabled and recording *base* data.
   * Telemetry will send additional ``main`` pings.
 
+  It defaults to ``true``, but is ``false`` on Android (Fennec) builds.
+
 ``toolkit.telemetry.enabled``
 
-  If ``unified`` is off, this controls whether the Telemetry module is enabled.
-  If ``unified`` is on, this controls whether to record *extended* data.
-  This preference is controlled through the `Preferences` dialog.
-
-  Note that the default value here of this pref depends on the define ``RELEASE_OR_BETA`` and the channel.
-  If ``RELEASE_OR_BETA`` is set, ``MOZ_TELEMETRY_ON_BY_DEFAULT`` gets set, which means this pref will default to ``true``.
-  This is overridden by the preferences code on the "beta" channel, the pref also defaults to ``true`` there.
+  If ``unified`` is off, this controls whether the Telemetry module is enabled. It can be set or unset via the `Preferences` dialog in Firefox for Android (Fennec).
+  If ``unified`` is on, this is locked to ``true`` if ``MOZ_UPDATE_CHANNEL`` is ``nightly`` or ``aurora`` or ``beta`` or ``default`` (which is the default value of ``MOZ_UPDATE_CHANNEL`` for developer builds). Otherwise it is locked to ``false``. This controls a diminishing number of things and is intended to be deprecated, and then removed.
 
 ``datareporting.healthreport.uploadEnabled``
 
-  Send the data we record if user has consented to FHR. This preference is controlled through the `Preferences` dialog.
+  If ``unified`` is true, this controls whether we send Telemetry data.
+  If ``unified`` is false, we don't use this value.
 
 ``toolkit.telemetry.archive.enabled``
 
   Allow pings to be archived locally. This can only be enabled if ``unified`` is on.
 
 ``toolkit.telemetry.server``
 
   The server Telemetry pings are sent to.
@@ -123,17 +121,17 @@ Preferences
   Allow the ``shutdown`` ping to be sent when the browser shuts down, from the second browsing session on, instead of the next restart, using the :doc:`ping sender <pingsender>`.
 
 ``toolkit.telemetry.shutdownPingSender.enabledFirstSession``
 
   Allow the ``shutdown`` ping to be sent using the :doc:`ping sender <pingsender>` from the first browsing session.
 
 ``toolkit.telemetry.firstShutdownPing.enabled``
 
-  Allow a duplicate of the shutdown ping from the first browsing session to be sent as a separate ``first-shutdown`` ping.
+  Allow a duplicate of the ``main`` shutdown ping from the first browsing session to be sent as a separate ``first-shutdown`` ping.
 
 ``toolkit.telemetry.newProfilePing.enabled``
 
   Enable the :doc:`../data/new-profile` ping on new profiles.
 
 ``toolkit.telemetry.newProfilePing.delay``
 
   Controls the delay after which the :doc:`../data/new-profile` is sent on new profiles.