tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

telemetry.rst (7991B)

      1 Telemetry
      2 =========
      3 
      4 This section describes existing telemetry probes measuring interaction with
      5 search engines from the browser UI.
      6 
      7 This document only covers Legacy telemetry, not Glean telemetry.
      8 Glean metrics are self-documenting and can be looked up in the Glean dictionary.
      9 
     10 Other search-related telemetry is recorded by Toolkit such as search service
     11 telemetry and telemetry related to fetching search suggestions. Toolkit search
     12 telemetry is relevant to Firefox as well as other consumers of Toolkit. See
     13 :doc:`/toolkit/search/Telemetry` in the Toolkit documentation for details.
     14 
     15 .. contents::
     16   :depth: 2
     17 
     18 
     19 Glossary
     20 --------
     21 
     22 SAP
     23  Search Access Point, a search that a user performs by visiting
     24  via one of Firefox's access points. The search may or may not have an
     25  associated partner code.
     26 
     27 SERP
     28  A search engine results page.
     29 
     30 Persisted Search
     31  When a user has the following preference values (only applies
     32  when the search bar isn't present in any toolbar or overflow panel):
     33 
     34    - ``browser.urlbar.showSearchTerms.enabled``: ``true``
     35    - ``browser.urlbar.showSearchTerms.featureGate``: ``true``
     36 
     37  and does the following:
     38 
     39    - Starts a search from the urlbar or context menu.
     40    - Loads the default search engine results page.
     41 
     42  the search term will persist in the Urlbar, causing it to enter a Persisted Search state.
     43 
     44 .. _serp-definitions:
     45 
     46 Definitions
     47 -----------
     48 
     49 ``organic``
     50  A search that a user performs by visiting a search engine directly.
     51 
     52 ``tagged``
     53  Refers to a page that is tagged with an associated partner code.
     54  It may or may not have originated via a SAP.
     55 
     56 ``tagged-follow-on``
     57  Refers to a page that is tagged with an associated partner code and has been identified
     58  as a follow-on search. It may or may not have originated via a SAP.
     59 
     60 Search probes relevant to front-end searches
     61 --------------------------------------------
     62 
     63 The Address Bar is an integral part of search and has `additional telemetry of its own`_.
     64 
     65 BrowserSearchTelemetry.sys.mjs
     66 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     67 
     68 This telemetry is handled by `BrowserSearchTelemetry.sys.mjs`_.
     69 
     70 sap.counts
     71 ^^^^^^^^^^
     72 
     73  See the `sap.counts Event documentation`_ for more information.
     74 
     75 SEARCH_COUNTS - SAP usage
     76 ^^^^^^^^^^^^^^^^^^^^^^^^^
     77 
     78  Note: This probe is reflected into the Glean probe ``sap.deprecated_counts``,
     79  which should not be used for ongoing measurements. Use the new ``sap.counts``
     80  event instead.
     81 
     82  This histogram tracks search engines and Search Access Points. It is augmented
     83  by multiple SAPs, including the urlbar.
     84  It's a keyed histogram, the keys are strings made up of search engine names
     85  and SAP names, for example ``google.urlbar``.
     86  For each key, this records the count of searches made using that engine and SAP.
     87  SAP names can be:
     88 
     89    - ``alias`` This is when using an alias (like ``@google``) in the urlbar.
     90      Note there is often confusion between the terms alias and keyword, and
     91      they may be used inappropriately: aliases refer to search engines, while
     92      keywords refer to bookmarks. We expect no results for this SAP in Firefox
     93      83+, since urlbar-searchmode replaces it.
     94    - ``abouthome``
     95    - ``contextmenu``
     96    - ``newtab``
     97    - ``searchbar``
     98    - ``system``
     99    - ``urlbar`` Except aliases and search mode.
    100    - ``urlbar-handoff`` Used when searching from about:newtab.
    101    - ``urlbar-persisted`` Used when searching from the Urlbar while it
    102      was in a Persisted Search state.
    103    - ``urlbar-searchmode`` Used when the Urlbar is in search mode.
    104    - ``webextension``
    105 
    106 browser.engagement.navigation.*
    107 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    108 
    109  These keyed scalars track search through different SAPs, for example the
    110  urlbar is tracked by ``browser.engagement.navigation.urlbar``.
    111  It counts loads triggered in a subsession from the specified SAP, broken down
    112  by the originating action.
    113  Possible SAPs are:
    114 
    115    - ``urlbar``  Except search mode.
    116    - ``urlbar_handoff`` Used when searching from about:newtab.
    117    - ``urlbar_persisted`` Used when searching from the Urlbar while it
    118      was in a Persisted Search state.
    119    - ``urlbar_searchmode``  Used when the Urlbar is in search mode.
    120    - ``searchbar``
    121    - ``about_home``
    122    - ``about_newtab``
    123    - ``contextmenu``
    124    - ``webextension``
    125    - ``system`` Indicates a search from the command line.
    126 
    127  Recorded actions may be:
    128 
    129    - ``search``
    130      Used for any search from ``contextmenu``, ``system`` and ``webextension``.
    131    - ``search_alias``
    132      For ``urlbar``, indicates the user confirmed a search through an alias.
    133    - ``search_enter``
    134      For ``about_home`` and ``about:newtab`` this counts any search.
    135      For the other SAPs it tracks typing and then pressing Enter.
    136    - ``search_formhistory``
    137      For ``urlbar``, indicates the user picked a form history result.
    138    - ``search_oneoff``
    139      For ``urlbar`` or ``searchbar``, indicates the user confirmed a search
    140      using a one-off button.
    141    - ``search_suggestion``
    142      For ``urlbar`` or ``searchbar``, indicates the user confirmed a search
    143      suggestion.
    144 
    145 SearchSERPTelemetry.sys.mjs
    146 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
    147 
    148 This telemetry is handled by `SearchSERPTelemetry.sys.mjs and the associated parent/child actors`_.
    149 
    150 browser.search.content.*
    151 ^^^^^^^^^^^^^^^^^^^^^^^^
    152 
    153  These keyed scalars track counts of SERP page loads.
    154 
    155  The key format is ``<provider>:[tagged|tagged-follow-on|organic]:[<code>|other|none]``.
    156  The values in angled brackets will be replaced by real values based on the URL of the
    157  SERP page. The key format is built from:
    158 
    159  - ``<provider>`` The name of the provider. This is not linked to search engine
    160    ids, as the search may have been generated organically.
    161  - ``[tagged|tagged-follow-on|organic]`` The type of SERP load. See the
    162    :ref:`definitions section above <serp-definitions>`.
    163  - ``[<code>|other|none]`` Details of the code associated with the SERP load:
    164 
    165    - ``<code>`` The partner code found in the URL. This is only for partners
    166      associated with the product.
    167    - ``other`` The SERP load had a partner code, but it is not recognised as
    168      an associated partner or an organic code.
    169    - ``none`` The SERP load had no partner codes, or it was a recognised organic code,
    170      e.g. some sites assign their own codes for searches.
    171 
    172  They are broken down by the originating SAP where known:
    173 
    174  - ``urlbar``  Except search mode.
    175  - ``urlbar_handoff`` Used when searching from about:newtab.
    176  - ``urlbar_persisted`` Used when searching from the Urlbar while it
    177    was in a Persisted Search state.
    178  - ``urlbar_searchmode``  Used when the Urlbar is in search mode.
    179  - ``searchbar``
    180  - ``about_home``
    181  - ``about_newtab``
    182  - ``contextmenu``
    183  - ``webextension``
    184  - ``system`` Indicates a search from the command line.
    185  - ``tabhistory`` Indicates a search was counted as a result of the user loading it from the tab history.
    186  - ``reload`` Indicates a search was counted as a result of reloading the page.
    187  - ``unknown`` Indicates the origin was unknown.
    188 
    189 browser.search.withads.*
    190 ^^^^^^^^^^^^^^^^^^^^^^^^
    191 
    192  These keyed scalar track counts of SERP pages with adverts displayed. The key
    193  format is ``<provider>:<tagged|organic>``.
    194 
    195  They are broken down by the originating SAP where known, the list of SAP
    196  is the same as for ``browser.search.content.*``.
    197 
    198 browser.search.adclicks.*
    199 ^^^^^^^^^^^^^^^^^^^^^^^^^
    200 
    201  This is the same as ```browser.search.withads.*`` but tracks counts for them
    202  clicks of adverts on SERP pages.
    203 
    204 .. _additional telemetry of its own: /browser/urlbar/telemetry.html
    205 .. _SearchSERPTelemetry.sys.mjs and the associated parent/child actors: https://searchfox.org/mozilla-central/search?q=&path=SearchSERPTelemetry*.sys.mjs&case=false&regexp=false
    206 .. _BrowserSearchTelemetry: https://searchfox.org/mozilla-central/source/browser/components/search/BrowserSearchTelemetry.sys.mjs
    207 .. _sap.counts Event documentation: https://dictionary.telemetry.mozilla.org/apps/firefox_desktop/metrics/sap_counts