Bug 991757 - add BrowserUITelemetry documentation, r=bsmedberg,jaws, DONTBUILD because docs-only
authorGijs Kruitbosch <gijskruitbosch@gmail.com>
Tue, 26 Aug 2014 12:16:24 +0100
changeset 201696 a8944add4cb603273a8d62b7103f48368f8b0689
parent 201695 11930a45d9a7754b4ee63cdb20d960ba848cfab6
child 201697 d851690b8255d2673c8a6f5350e061c442ae87c6
child 201775 f688f262758d59fd295355d1225da0313f32b8de
push id27378
push userkwierso@gmail.com
push dateWed, 27 Aug 2014 00:10:17 +0000
treeherdermozilla-central@d851690b8255 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersbsmedberg, jaws, DONTBUILD
bugs991757
milestone34.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 991757 - add BrowserUITelemetry documentation, r=bsmedberg,jaws, DONTBUILD because docs-only
browser/docs/UITelemetry.rst
browser/docs/index.rst
browser/moz.build
new file mode 100644
--- /dev/null
+++ b/browser/docs/UITelemetry.rst
@@ -0,0 +1,107 @@
+=======================
+UITelemetry data format
+=======================
+
+UI Telemetry sends its data as a JSON blob. This document describes the different parts
+of the JSON blob.
+
+``toolbars``
+------------
+
+This tracks the state of the user's UI customizations. It has the following properties:
+
+- ``sizemode`` - string indicating whether the window is in maximized, normal (restored) or
+  fullscreen mode;
+- ``bookmarksBarEnabled`` - boolean indicating whether the bookmarks bar is visible;
+- ``menuBarEnabled`` - boolean indicating whether the menu bar is visible (always false on OS X);
+- ``titleBarEnabled`` - boolean indicating whether the (real) titlebar is visible (rather than
+  having tabs in the titlebar);
+- ``defaultKept`` - list of strings identifying toolbar buttons and items that are still in their
+  default position. Only the IDs of builtin widgets are sent (ie not add-on widgets);
+- ``defaultMoved`` - list of strings identifying toolbar buttons and items that are no longer in
+  their default position, but have not been removed to the palette. Only the IDs of builtin widgets
+  are sent (ie not add-on widgets);
+- ``nondefaultAdded`` - list of strings identifying toolbar buttons and items that have been added
+  from the palette. Only the IDs of builtin widgets are sent (ie not add-on widgets);
+- ``defaultRemoved`` - list of strings identifying toolbar buttons and items that are in the
+  palette that are elsewhere by default. Only the IDs of builtin widgets are sent
+  (ie not add-on widgets);
+- ``addonToolbars`` - the number of non-default toolbars that are customizable. 1 by default
+  because it counts the add-on bar shim;
+- ``visibleTabs`` - array of the number of visible tabs per window;
+- ``hiddenTabs`` - array of the number of hidden tabs per window (ie tabs in panorama groups which
+  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.
+
+``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:
+
+- ``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``
+  or ``other``, depending on the kind of item clicked. Note that this is not tracked on OS X, where
+  we can't listen for these events because of the global menubar.
+- ``click-bookmarks-menu-button`` is also similar, with the item IDs being replaced by:
+   - ``menu`` for clicks on the 'menu' part of the item;
+   - ``add`` for clicks that add a bookmark;
+   - ``edit`` for clicks that open the panel to edit an existing bookmark;
+   - ``in-panel`` for clicks when the button is in the menu panel, and clicking it does none of the
+     above;
+- ``customize`` tracks different types of customization events without the ``left``, ``middle`` and
+  ``right`` distinctions. The different events are the following, with each storing a count of the
+  number of times they occurred:
+   - ``start`` counts the number of times the user starts customizing;
+   - ``add`` counts the number of times an item is added somewhere from the palette;
+   - ``move`` counts the number of times an item is moved somewhere else (but not to the palette);
+   - ``remove`` counts the number of times an item is removed to the palette;
+   - ``reset`` counts the number of times the 'restore defaults' button is used;
+
+
+``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.
+
+``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;
+- ``link`` if the user opened the context menu for a link
+- ``image-link`` if the user opened the context menu on an image or canvas that's a link;
+- ``image`` if the user opened the context menu on an image (that isn't a link);
+- ``canvas`` if the user opened the context menu on a canvas (that isn't a link);
+- ``media`` if the user opened the context menu on an HTML video or audio element;
+- ``input`` if the user opened the context menu on a text input element;
+- ``social`` if the user opened the context menu inside a social frame;
+- ``other`` for all other openings of the content menu;
+
+Each of these objects (if they exist) then gets a "withcustom" and/or a "withoutcustom" property
+for context menus opened with custom page-created items and without them, and each of those
+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.
+
new file mode 100644
--- /dev/null
+++ b/browser/docs/index.rst
@@ -0,0 +1,9 @@
+=======
+Firefox
+=======
+
+This is the nascent documentation of the Firefox front-end code.
+
+.. toctree::
+   :maxdepth: 1
+
--- a/browser/moz.build
+++ b/browser/moz.build
@@ -1,16 +1,18 @@
 # -*- Mode: python; c-basic-offset: 4; indent-tabs-mode: nil; tab-width: 40 -*-
 # vim: set filetype=python:
 # This Source Code Form is subject to the terms of the Mozilla Public
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
 
 CONFIGURE_SUBST_FILES += ['installer/Makefile']
 
+SPHINX_TREES['browser'] = 'docs'
+
 DIRS += [
     'base',
     'components',
     'experiments',
     'fuel',
     'locales',
     'modules',
     'themes',