Bug 1309256 - Add documentation for BrowserUsageTelemetry. r=gfritzsche
authorAlessio Placitelli <alessio.placitelli@gmail.com>
Wed, 09 Nov 2016 00:18:00 +0100
changeset 321884 e9d203fbb3f31f66311b2c9f731dd475b5470c92
parent 321883 166114662d40d11ceecbd1931dafa15191b07170
child 321885 b1d62e7171efc9d8ec596456399b2d35737d865b
push id30937
push usercbook@mozilla.com
push dateThu, 10 Nov 2016 16:00:02 +0000
treeherdermozilla-central@d38d06f85ef5 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersgfritzsche
bugs1309256
milestone52.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 1309256 - Add documentation for BrowserUsageTelemetry. r=gfritzsche MozReview-Commit-ID: GVclrfo5Zhl
browser/docs/BrowserUsageTelemetry.rst
browser/docs/index.rst
toolkit/components/telemetry/docs/collection/index.rst
new file mode 100644
--- /dev/null
+++ b/browser/docs/BrowserUsageTelemetry.rst
@@ -0,0 +1,28 @@
+.. _browserusagetelemetry:
+
+=======================
+Browser Usage Telemetry
+=======================
+
+The `BrowserUsageTelemetry.jsm <https://dxr.mozilla.org/mozilla-central/source/browser/modules/BrowserUsageTelemetry.jsm>`_ module is the main module for measurements regarding the browser usage (e.g. tab and window counts, search counts, ...).
+
+The measurements recording begins right after the ``SessionStore`` has finished restoring the session (i.e. restoring tabs/windows after Firefox starts).
+
+Search telemetry
+================
+This module exposes the ``recordSearch`` method, which serves as the main entry point for recording search related Telemetry. It records only the search *counts* per engine and the origin of the search, but nothing pertaining the search contents themselves.
+
+As the transition to the ``BrowserUsageTelemetry`` happens, the ``recordSearch`` calls are dispatched through `BrowserSearch.recordSearchInTelemetry <https://dxr.mozilla.org/mozilla-central/rev/3e73fd638e687a4d7f46613586e5156b8e2af846/browser/base/content/browser.js#3752>`_, that is called by all the search related UI components (urlbar, searchbar, context menu and about\:\* pages).
+
+A list of the components recording search Telemetry can be found using the following `DXR search <https://dxr.mozilla.org/mozilla-central/search?q=recordSearchInTelemetry>`_.
+
+Measured interactions
+=====================
+The usage telemetry module currently measures these interactions with the browser:
+
+- *tab and window engagement*: counts the number of non-private tabs and windows opened in a subsession, after the session is restored (see e.g. ``browser.engagement.max_concurrent_tab_count``);
+- *URI loads*: counts the number of page loads (doesn't track and send the addresses, just the counts) directly triggered by the users (see ``browser.engagement.total_uri_count``);
+- *navigation events*: at this time, this only counts the number of time a page load is triggered by a particular UI interaction (e.g. by searching through the URL bar, see ``browser.engagement.navigation.urlbar``).
+
+
+Please see `Scalars.yaml <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Scalars.yaml>`_ for the full list of tracked interactions.
--- a/browser/docs/index.rst
+++ b/browser/docs/index.rst
@@ -4,8 +4,9 @@ Firefox
 
 This is the nascent documentation of the Firefox front-end code.
 
 .. toctree::
    :maxdepth: 1
 
    DirectoryLinksProvider
    UITelemetry
+   BrowserUsageTelemetry
--- a/toolkit/components/telemetry/docs/collection/index.rst
+++ b/toolkit/components/telemetry/docs/collection/index.rst
@@ -24,8 +24,12 @@ The current data collection possibilitie
    :titlesonly:
    :hidden:
    :glob:
 
    scalars
    histograms
    measuring-time
    custom-pings
+
+Browser Usage Telemetry
+~~~~~~~~~~~~~~~~~~~~~~~
+For more information, see :ref:`browserusagetelemetry`.