Bug 1821392 - Change Search and Address Bar telemetry docs to use titles for the probe names. r=Standard8

Differential Revision: https://phabricator.services.mozilla.com/D172203
2023-03-10 12:31:59 +00:00 · 2023-03-10 12:31:59 +00:00 · 3e5c4be1ba
--- a/browser/components/search/docs/telemetry.rst
+++ b/browser/components/search/docs/telemetry.rst
@ -62,6 +62,8 @@ BrowserSearchTelemetry.sys.mjs
 This telemetry is handled by `BrowserSearchTelemetry.sys.mjs`_.

 SEARCH_COUNTS - SAP usage
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
  This histogram tracks search engines and Search Access Points. It is augmented
  by multiple SAPs, including the urlbar.
  It's a keyed histogram, the keys are strings made up of search engine names
@ -87,6 +89,8 @@ SEARCH_COUNTS - SAP usage
    - ``webextension``

 browser.engagement.navigation.*
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
  These keyed scalars track search through different SAPs, for example the
  urlbar is tracked by ``browser.engagement.navigation.urlbar``.
  It counts loads triggered in a subsession from the specified SAP, broken down
@ -124,6 +128,8 @@ browser.engagement.navigation.*
      suggestion.

 navigation.search (OBSOLETE)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
  This is a legacy and disabled event telemetry that is currently under
  discussion for removal or modernization. It can't be enabled through a pref.
  it's more or less equivalent to browser.engagement.navigation, but can also
@ -135,6 +141,8 @@ SearchSERPTelemetry.sys.mjs
 This telemetry is handled by `SearchSERPTelemetry.sys.mjs and the associated parent/child actors`_.

 browser.search.content.*
+^^^^^^^^^^^^^^^^^^^^^^^^
+
  These keyed scalar track counts of SERP page loads. The key format is
  ``<provider>:[tagged|tagged-follow-on|organic]:[<code>|other|none]``.

@ -156,6 +164,8 @@ browser.search.content.*
  - ``unknown`` Indicates the origin was unknown.

 browser.search.withads.*
+^^^^^^^^^^^^^^^^^^^^^^^^
+
  These keyed scalar track counts of SERP pages with adverts displayed. The key
  format is ``<provider>:<tagged|organic>``.

@ -163,6 +173,8 @@ browser.search.withads.*
  is the same as for ``browser.search.content.*``.

 browser.search.adclicks.*
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
  This is the same as ```browser.search.withads.*`` but tracks counts for them
  clicks of adverts on SERP pages.

--- a/browser/components/urlbar/docs/telemetry.rst
+++ b/browser/components/urlbar/docs/telemetry.rst
@ -15,14 +15,20 @@ Histograms
 ----------

 PLACES_AUTOCOMPLETE_1ST_RESULT_TIME_MS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  This probe tracks the amount of time it takes to get the first result.
  It is an exponential histogram with values between 5 and 100.

 PLACES_AUTOCOMPLETE_6_FIRST_RESULTS_TIME_MS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  This probe tracks the amount of time it takes to get the first six results.
  It is an exponential histogram with values between 50 and 1000.

 FX_URLBAR_SELECTED_RESULT_METHOD
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  This probe tracks how a result was picked by the user from the list.
  It is a categorical histogram with these values:

@ -49,6 +55,8 @@ FX_URLBAR_SELECTED_RESULT_METHOD
    not pick it. Then the user could press Enter. This is no more possible.

 FX_URLBAR_ZERO_PREFIX_DWELL_TIME_MS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  This probe records the amount of time the zero-prefix view was shown; that is,
  the time from when it was opened to the time it was closed. "Zero-prefix"
  means the search string was empty, so the zero-prefix view is the view that's
@ -59,6 +67,8 @@ FX_URLBAR_ZERO_PREFIX_DWELL_TIME_MS
  Firefox 110.0 in bug 1806765.

 PLACES_FRECENCY_RECALC_CHUNK_TIME_MS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  This records the time necessary to recalculate frecency of a chunk of pages,
  as defined in the `PlacesFrecencyRecalculator <https://searchfox.org/mozilla-central/source/toolkit/components/places/PlacesFrecencyRecalculator.sys.mjs>`_ module.

@ -66,6 +76,8 @@ Scalars
 -------

 urlbar.abandonment
+~~~~~~~~~~~~~~~~~~
+
  A uint recording the number of abandoned engagements in the urlbar. An
  abandonment occurs when the user begins using the urlbar but stops before
  completing the engagement. This can happen when the user clicks outside the
@ -73,17 +85,23 @@ urlbar.abandonment
  user switches to another window while the urlbar is focused.

 urlbar.autofill_deletion
+~~~~~~~~~~~~~~~~~~~~~~~~
+
  A uint recording the deletion count for autofilled string in the urlbar.
  This occurs when the user deletes whole autofilled string by BACKSPACE or
  DELETE key while the autofilled string is selected.

 urlbar.engagement
+~~~~~~~~~~~~~~~~~
+
  A uint recording the number of engagements the user completes in the urlbar.
  An engagement occurs when the user navigates to a page using the urlbar, for
  example by picking a result in the urlbar panel or typing a search term or URL
  in the urlbar and pressing the enter key.

 urlbar.impression.*
+~~~~~~~~~~~~~~~~~~~
+
  A uint recording the number of impression that was displaying when user picks
  any result.

@ -105,6 +123,8 @@ urlbar.impression.*
    For url type autofill.

 urlbar.tips
+~~~~~~~~~~~
+
  This is a keyed scalar whose values are uints and are incremented each time a
  tip result is shown, a tip is picked, and a tip's help button is picked. The
  keys are:
@ -185,6 +205,8 @@ urlbar.tips
    Incremented when the redirect search tip is shown.

 urlbar.searchmode.*
+~~~~~~~~~~~~~~~~~~~
+
  This is a set of keyed scalars whose values are uints incremented each
  time search mode is entered in the Urlbar. The suffix on the scalar name
  describes how search mode was entered. Possibilities include:
@ -240,6 +262,8 @@ urlbar.searchmode.*
  is done to reduce the number of keys used by these scalars.

 urlbar.picked.*
+~~~~~~~~~~~~~~~
+
  This is a set of keyed scalars whose values are uints incremented each
  time a result is picked from the Urlbar. The suffix on the scalar name
  is the result type. The keys for the scalars above are the 0-based index of
@ -349,6 +373,8 @@ urlbar.picked.*
  .. _preloaded site: https://searchfox.org/mozilla-central/source/browser/components/urlbar/UrlbarProviderPreloadedSites.jsm

 urlbar.picked.searchmode.*
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  This is a set of keyed scalars whose values are uints incremented each time a
  result is picked from the Urlbar while the Urlbar is in search mode. The
  suffix on the scalar name is the search mode entry point. The keys for the
@ -368,6 +394,8 @@ urlbar.picked.searchmode.*
    ``urlbar.picked.searchsuggestion`` and ``urlbar.picked.searchmode.oneoff``.

 urlbar.tabtosearch.*
+~~~~~~~~~~~~~~~~~~~~
+
  This is a set of keyed scalars whose values are uints incremented when a
  tab-to-search result is shown, once per engine per engagement. There are two
  sub-probes: ``urlbar.tabtosearch.impressions`` and
@ -383,6 +411,8 @@ urlbar.tabtosearch.*
    collected only on pre-release version of Firefox. See bug 1686330.

 urlbar.zeroprefix.abandonment
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  A uint recording the number of abandonments of the zero-prefix view.
  "Zero-prefix" means the search string was empty, so the zero-prefix view is
  the view that's shown when the user clicks in the urlbar before typing a
@ -392,6 +422,8 @@ urlbar.zeroprefix.abandonment
  introduced in Firefox 110.0 in bug 1806765.

 urlbar.zeroprefix.engagement
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  A uint recording the number of engagements in the zero-prefix view.
  "Zero-prefix" means the search string was empty, so the zero-prefix view is
  the view that's shown when the user clicks in the urlbar before typing a
@ -400,6 +432,8 @@ urlbar.zeroprefix.engagement
  view. This scalar was introduced in Firefox 110.0 in bug 1806765.

 urlbar.zeroprefix.exposure
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  A uint recording the number of times the user was exposed to the zero-prefix
  view; that is, the number of times it was shown. "Zero-prefix" means the
  search string was empty, so the zero-prefix view is the view that's shown when
@ -408,16 +442,22 @@ urlbar.zeroprefix.exposure
  was introduced in Firefox 110.0 in bug 1806765.

 urlbar.quickaction.impression
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  A uint recording the number of times the user was shown a quickaction, the
  key is in the form $key-$n where $n is the number of characters the user typed
  in order for the suggestion to show. See bug 1806024.

 urlbar.quickaction.picked
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
  A uint recording the number of times the user selected a quickaction, the
  key is in the form $key-$n where $n is the number of characters the user typed
  in order for the suggestion to show. See bug 1783155.

 places.*
+~~~~~~~~
+
  This is Places related telemetry.

  Valid result types are:
@ -473,6 +513,8 @@ the top sites feature.
    .. _custom pings: https://docs.telemetry.mozilla.org/cookbooks/new_ping.html#sending-a-custom-ping

 Top Sites Impression
+~~~~~~~~~~~~~~~~~~~~
+
  This records an impression when a sponsored top site is shown.

  - ``context_id``
@ -507,6 +549,8 @@ Changelog
 .. _1794022: https://bugzilla.mozilla.org/show_bug.cgi?id=1794022

 Top Sites Click
+~~~~~~~~~~~~~~~
+
  This records a click ping when a sponsored top site is clicked by the user.

  - ``context_id``
@ -542,9 +586,13 @@ Other telemetry relevant to the Address Bar
 -------------------------------------------

 Search Telemetry
+~~~~~~~~~~~~~~~~
+
  Some of the `search telemetry`_ is also relevant to the address bar.

 contextual.services.topsites.*
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  These keyed scalars instrument the impressions and clicks for sponsored top
  sites in the urlbar.
  The key is a combination of the source and the placement of the top sites link
@ -553,6 +601,8 @@ contextual.services.topsites.*
  Note that these scalars are shared with the top sites on the newtab page.

 Telemetry Environment
+~~~~~~~~~~~~~~~~~~~~~
+
  The following preferences relevant to the address bar are recorded in
  :doc:`telemetry environment data </toolkit/components/telemetry/data/environment>`:

@ -567,6 +617,8 @@ Telemetry Environment
      enabled in the urlbar. Defaults to false.

 Firefox Suggest
+~~~~~~~~~~~~~~~
+
  Telemetry specific to Firefox Suggest is described in the
  :doc:`firefox-suggest-telemetry` document.

@ -586,6 +638,8 @@ Event Telemetry
 The event telemetry is grouped under the ``urlbar`` category.

 Event Method
+~~~~~~~~~~~~
+
  There are two methods to describe the interaction with the urlbar:

  - ``engagement``
@ -598,6 +652,8 @@ Event Method
    focus.

 Event Value
+~~~~~~~~~~~
+
  This is how the user interaction started

  - ``typed``: The text was typed into the urlbar.
@ -622,6 +678,8 @@ Event Value
    cleared it and then typed a new string.

 Event Object
+~~~~~~~~~~~~
+
  These describe actions in the urlbar:

  - ``click``
@ -636,6 +694,8 @@ Event Object
    The user unfocused the urlbar. This is only valid for ``abandonment``.

 Event Extra
+~~~~~~~~~~~
+
  This object contains additional information about the interaction.
  Extra is a key-value store, where all the keys and values are strings.

--- a/toolkit/components/search/docs/Telemetry.rst
+++ b/toolkit/components/search/docs/Telemetry.rst
@ -12,22 +12,32 @@ Scalars
 -------

 browser.searchinit.init_result_status_code
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  Records the search service initialization code on startup. This is typically
  one of the error values in https://searchfox.org/mozilla-central/source/xpcom/base/ErrorList.py

 browser.searchinit.secure_opensearch_engine_count
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  Records the number of secure (i.e., using https) OpenSearch search
  engines a given user has installed

 browser.searchinit.insecure_opensearch_engine_count
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  Records the number of insecure (i.e., using http) OpenSearch search
  engines a given user has installed

 browser.searchinit.secure_opensearch_update_count
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  Records the number of OpenSearch search engines with secure updates
  enabled (i.e., using https) a given user has installed

 browser.searchinit.insecure_opensearch_update_count
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  Records the number of OpenSearch search engines with insecure updates
  enabled (i.e., using http) a given user has installed

@ -35,6 +45,8 @@ Keyed Scalars
 -------------

 browser.searchinit.engine_invalid_webextension
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  Records the WebExtension ID of a search engine where the saved search engine
  settings do not match the WebExtension.

@ -48,6 +60,8 @@ Histograms
 ----------

 SEARCH_SUGGESTIONS_LATENCY_MS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
  This histogram records the latency in milliseconds of fetches to the
  suggestions endpoints of search engines, or in other words, the time from
  Firefox's request to a suggestions endpoint to the time Firefox receives a