Telemetry¶
This section describes existing telemetry probes measuring interaction with search engines from the browser UI.
Other search-related telemetry is recorded by Toolkit such as search service telemetry and telemetry related to fetching search suggestions. Toolkit search telemetry is relevant to Firefox as well as other consumers of Toolkit. See Telemetry in the Toolkit documentation for details.
Glossary¶
- SAP
Search Access Point, a search that a user performs by visiting via one of Firefox’s access points using the associated partner codes.
- SERP
A search engine results page.
- Persisted Search
When a user has the following preference values:
browser.urlbar.showSearchTerms.enabled
:true
browser.urlbar.showSearchTerms.featureGate
:true
browser.search.widget.inNavBar
:false
and does the following:
Starts a search from the urlbar or context menu.
Loads the default search engine results page.
the search term will persist in the Urlbar, causing it to enter a Persisted Search state.
Definitions¶
organic
A search that a user performs by visiting a search engine directly.
tagged
Refers to a page that is tagged with an associated partner code. It may or may not have originated via a SAP.
tagged-follow-on
Refers to a page that is tagged with an associated partner code and has been identified as a follow-on search. It may or may not have originated via a SAP.
Search probes relevant to front-end searches¶
The Address Bar is an integral part of search and has additional telemetry of its own.
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 and SAP names, for example
google.urlbar
. For each key, this records the count of searches made using that engine and SAP. SAP names can be:
alias
This is when using an alias (like
abouthome
contextmenu
newtab
searchbar
system
urlbar
Except aliases and search mode.
urlbar-handoff
Used when searching from about:newtab.
urlbar-persisted
Used when searching from the Urlbar while it was in a Persisted Search state.
urlbar-searchmode
Used when the Urlbar is in search mode.
webextension
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]
.They are broken down by the originating SAP where known:
urlbar
Except search mode.
urlbar_handoff
Used when searching from about:newtab.
urlbar_persisted
Used when searching from the Urlbar while it was in a Persisted Search state.
urlbar_searchmode
Used when the Urlbar is in search mode.
searchbar
about_home
about_newtab
contextmenu
webextension
system
Indicates a search from the command line.
tabhistory
Indicates a search was counted as a result of the user loading it from the tab history.
reload
Indicates a search was counted as a result of reloading the page.
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>
.They are broken down by the originating SAP where known, the list of SAP 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.