From 3e5c4be1ba4dc9021a257efa6f0efbbfe358fa1e Mon Sep 17 00:00:00 2001 From: Noah Date: Fri, 10 Mar 2023 12:31:59 +0000 Subject: [PATCH] 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 --- browser/components/search/docs/telemetry.rst | 12 ++++ browser/components/urlbar/docs/telemetry.rst | 60 ++++++++++++++++++++ toolkit/components/search/docs/Telemetry.rst | 14 +++++ 3 files changed, 86 insertions(+) diff --git a/browser/components/search/docs/telemetry.rst b/browser/components/search/docs/telemetry.rst index 9fca58932ff9..b00e7eb91155 100644 --- 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 ``:[tagged|tagged-follow-on|organic]:[|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 ``:``. @@ -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. diff --git a/browser/components/urlbar/docs/telemetry.rst b/browser/components/urlbar/docs/telemetry.rst index be1559439145..f5c0122c4ac4 100644 --- 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 `_ 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 `: @@ -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. diff --git a/toolkit/components/search/docs/Telemetry.rst b/toolkit/components/search/docs/Telemetry.rst index 61c7458da5af..8bd66696f0e4 100644 --- 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