Bug 987333 - Add documentation for UITour and buckets to BrowserUITelemetry docs. r=mconley
authorBlair McBride <bmcbride@mozilla.com>
Tue, 06 Jan 2015 19:13:46 +1300
changeset 248055 9477cb31bf80a66b74c27a3848891f1f13a4667f
parent 248054 77c0488fa25d712dfc3f0d1fb9161e07cf2a2693
child 248056 1f6ca2c7d05a89a27e8b22df0bfc19953cb8857b
push id4489
push userraliiev@mozilla.com
push dateMon, 23 Feb 2015 15:17:55 +0000
treeherdermozilla-beta@fd7c3dc24146 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersmconley
bugs987333
milestone37.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 987333 - Add documentation for UITour and buckets to BrowserUITelemetry docs. r=mconley
browser/docs/UITelemetry.rst
browser/docs/index.rst
--- a/browser/docs/UITelemetry.rst
+++ b/browser/docs/UITelemetry.rst
@@ -33,25 +33,33 @@ This tracks the state of the user's UI c
   are not the current group);
 - ``countableEvents`` - please refer to the next section.
 - ``durations`` - an object mapping descriptions to duration records, which records the amount of
   time a user spent doing something. Currently only has one property:
    - ``customization`` - how long a user spent customizing the browser. This is an array of
      objects, where each object has a ``duration`` property indicating the time in milliseconds,
      and a ``bucket`` property indicating a bucket in which the duration info falls.
 
+
+.. _UITelemetry_countableEvents:
+
 ``countableEvents``
 -------------------
 
 Countable events are stored under the ``toolbars`` section. They count the number of times certain
 events happen. No timing or other correlating information is stored - purely the number of times
 things happen.
 
-``countableEvents`` is an object with properties representing buckets. In each bucket, there is an
-object with the following properties:
+``countableEvents`` contains a list of buckets as its properties. A bucket represents the state the browser was in when these events occurred, such as currently running an interactive tour. There are 3 types of buckets:
+
+- ``__DEFAULT__`` - No bucket, for times when the browser is not in any special state.
+- ``bucket_<NAME>`` - Normal buckets, for when the browser is in a special state. The ``<NAME>`` in the bucket ID is the name associated with the bucket and may be further broken down into parts by the ``|`` character.
+- ``bucket_<NAME>|<INTERVAL>`` - Expiring buckets, which are similar to a countdown timer. The ``<INTERVAL>`` in the bucket ID describes the time interval the recorded event happened in. The intervals are ``1m`` (one minute), ``3m`` (three minutes), ``10m`` (ten minutes), and ``1h`` (one hour). After one hour, the ``__DEFAULT__`` bucket is automatically used again.
+
+Each bucket is an object with the following properties:
 
 - ``click-builtin-item`` is an object tracking clicks on builtin customizable toolbar items, keyed
   off the item IDs, with an object for each item with keys ``left``, ``middle`` and ``right`` each
   storing a number indicating how often the respective type of click has happened.
 - ``click-menu-button`` is the same, except the item ID is always 'button'.
 - ``click-bookmarks-bar`` is the same, with the item IDs being replaced by either ``container`` for
   clicks on bookmark or livemark folders, and ``item`` for individual bookmarks.
 - ``click-menubar`` is similar, with the item IDs being replaced by one of ``menu``, ``menuitem``
@@ -81,18 +89,27 @@ object with the following properties:
     - ``selection`` searches records selections of search suggestions.  They include
       the source, the index of the selection, and the kind of selection (mouse or
       enter key).  Selection searches are also counted in their sources.
 
 
 
 ``UITour``
 ----------
-The UI Tour has its own section in the UI Telemetry output, outside of the ``toolbars`` section.
-It has a single property ``seenPageIDs`` which tracks which UI Tour pages have been run.
+The UITour API provides ways for pages on trusted domains to safely interact with the browser UI and request it to perform actions such as opening menus and showing highlights over the browser chrome - for the purposes of interactive tours. We track some usage of this API via the ``UITour`` object in the UI Telemetry output.
+
+Each page is able to register itself with an identifier, a ``Page ID``. A list of Page IDs that have been seen over the last 8 weeks is available via ``seenPageIDs``.
+
+Page IDs are also used to identify buckets for :ref:`UITelemetry_countableEvents`, in the following circumstances:
+
+- The current tab is a tour page. This will be a normal bucket with the name ``UITour|<PAGEID>``, where ``<PAGEID>`` is the page's registered ID. This will result in bucket IDs such as ``bucket_UITour|australis-tour``.
+- A tour tab is open but another tab is active. This will be an expiring bucket with the name ``UITour|<PAGEID>|inactive``. This will result in bucket IDs such as ``bucket_UITour|australis-tour|inactive|1m``.
+- A tour tab has recently been open but has been closed. This will be an expiring bucket with the name ``UITour|<PAGEID>|closed``. This will result in bucket IDs such as ``bucket_UITour|australis-tour|closed|10m``.
+
+
 
 ``contextmenu``
 ---------------
 We track context menu interactions to figure out which ones are most often used and/or how
 effective they are. In the ``contextmenu`` object, we first store things per-bucket. Next, we
 divide the following different context menu situations:
 
 - ``selection`` if there is content on the page that's selected on which the user clicks;
@@ -110,9 +127,8 @@ for context menus opened with custom pag
 properties holds an object with IDs corresponding to a count of how often an item with that ID was
 activated in the context menu. Only builtin context menu items are tracked, and besides those items
 there are four special items which get counts:
 
 - ``close-without-interaction`` is incremented when the user closes the context menu without interacting with it;
 - ``custom-page-item`` is incremented when the user clicks an item that was created by the page;
 - ``unknown`` is incremented when an item without an ID was clicked;
 - ``other-item`` is incremented when an add-on-provided menuitem is clicked.
-
--- a/browser/docs/index.rst
+++ b/browser/docs/index.rst
@@ -2,8 +2,9 @@
 Firefox
 =======
 
 This is the nascent documentation of the Firefox front-end code.
 
 .. toctree::
    :maxdepth: 1
 
+   UITelemetry