telemetry.rst (31989B)
1 Telemetry 2 ========= 3 4 This section describes existing telemetry probes measuring interaction with the 5 Address Bar. 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 For telemetry specific to Firefox Suggest, see the 11 :doc:`firefox-suggest-telemetry` document. 12 13 .. contents:: 14 :depth: 2 15 16 17 Histograms 18 ---------- 19 20 PLACES_AUTOCOMPLETE_1ST_RESULT_TIME_MS 21 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 22 23 This probe tracks the amount of time it takes to get the first result. 24 It is an exponential histogram with values between 5 and 100. 25 26 Changelog 27 Firefox 138 28 Mirrored from Glean (urlbar.autocomplete_first_result_time) . (See bug 1938938) 29 30 PLACES_AUTOCOMPLETE_6_FIRST_RESULTS_TIME_MS 31 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 32 33 This probe tracks the amount of time it takes to get the first six results. 34 It is an exponential histogram with values between 50 and 1000. 35 36 Changelog 37 Firefox 138 38 Mirrored from Glean (urlbar.autocomplete_sixth_result_time). (See bug 1938938) 39 40 FX_URLBAR_SELECTED_RESULT_METHOD 41 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 42 43 NOTE: This histogram has been completely removed, as its data is now 44 collected as part of the `urlbar.engagement` Glean event. (See bug 1932707) 45 46 This probe tracks how a result was picked by the user from the list. 47 It is a categorical histogram with these values: 48 49 - ``enter`` 50 The user pressed Enter without selecting a result first. 51 This most likely happens when the user confirms the default preselected 52 result (aka *heuristic result*), or when they select with the keyboard a 53 one-off search button and confirm with Enter. 54 - ``enterSelection`` 55 The user selected a result, but not using Tab or the arrow keys, and then 56 pressed Enter. This is a rare and generally unexpected event, there may be 57 exotic ways to select a result we didn't consider, that are tracked here. 58 Look at arrowEnterSelection and tabEnterSelection for more common actions. 59 - ``click`` 60 The user clicked on a result. 61 - ``arrowEnterSelection`` 62 The user selected a result using the arrow keys, and then pressed Enter. 63 - ``tabEnterSelection`` 64 The first key the user pressed to select a result was the Tab key, and then 65 they pressed Enter. Note that this means the user could have used the arrow 66 keys after first pressing the Tab key. 67 - ``rightClickEnter`` 68 Before QuantumBar, it was possible to right-click a result to highlight but 69 not pick it. Then the user could press Enter. This is no more possible. 70 71 FX_URLBAR_ZERO_PREFIX_DWELL_TIME_MS 72 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 73 74 This probe records the amount of time the zero-prefix view was shown; that is, 75 the time from when it was opened to the time it was closed. "Zero-prefix" 76 means the search string was empty, so the zero-prefix view is the view that's 77 shown when the user clicks in the urlbar before typing a search string. Often 78 it's also called the "top sites" view since normally it shows the user's top 79 sites. This is an exponential histogram whose values range from 0 to 60,000 80 with 50 buckets. Values are in milliseconds. This histogram was introduced in 81 Firefox 110.0 in bug 1806765. 82 83 Changelog 84 Firefox 138 85 Removed completely. (See bug 1938938) 86 87 PLACES_FRECENCY_RECALC_CHUNK_TIME_MS 88 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 89 90 This records the time necessary to recalculate frecency of a chunk of pages, 91 as defined in the `PlacesFrecencyRecalculator <https://searchfox.org/mozilla-central/source/toolkit/components/places/PlacesFrecencyRecalculator.sys.mjs>`_ module. 92 93 Scalars 94 ------- 95 96 urlbar.abandonment 97 ~~~~~~~~~~~~~~~~~~ 98 99 NOTE: This telemetry is no longer collected. See changelog below. 100 101 A uint recording the number of abandoned engagements in the urlbar. An 102 abandonment occurs when the user begins using the urlbar but stops before 103 completing the engagement. This can happen when the user clicks outside the 104 urlbar to focus a different part of the window. It can also happen when the 105 user switches to another window while the urlbar is focused. 106 107 Changelog 108 Firefox 134 109 Legacy ``urlbar.abandonment`` telemetry mirrored to Glean. (See bug 1927093) 110 Firefox 137 111 Legacy ``urlbar.abandonment`` telemetry and Glean ``urlbar.abandonment_count`` telemetry 112 removed completely. (See bug 1932711) 113 114 urlbar.autofill_deletion 115 ~~~~~~~~~~~~~~~~~~~~~~~~ 116 117 A uint recording the deletion count for autofilled string in the urlbar. 118 This occurs when the user deletes whole autofilled string by BACKSPACE or 119 DELETE key while the autofilled string is selected. 120 121 urlbar.engagement 122 ~~~~~~~~~~~~~~~~~ 123 124 NOTE: This telemetry is no longer collected. See changelog below. 125 126 A uint recording the number of engagements the user completes in the urlbar. 127 An engagement occurs when the user navigates to a page using the urlbar, for 128 example by picking a result in the urlbar panel or typing a search term or URL 129 in the urlbar and pressing the enter key. 130 131 Changelog 132 Firefox 134 133 Legacy ``urlbar.engagement`` telemetry mirrored to Glean. (See bug 1927093) 134 Firefox 137 135 Legacy ``urlbar.engagement`` telemetry and Glean ``urlbar.engagement_count`` telemetry 136 removed completely. (See bug 1932711) 137 138 urlbar.impression.* 139 ~~~~~~~~~~~~~~~~~~~ 140 141 NOTE: This telemetry is no longer collected. See changelog below. 142 143 A uint recording the number of impression that was displaying when user picks 144 any result. 145 146 - ``autofill_about`` 147 For about-page type autofill. 148 - ``autofill_adaptive`` 149 For adaptive history type autofill. 150 - ``autofill_origin`` 151 For origin type autofill. 152 - ``autofill_other`` 153 Counts how many times some other type of autofill result that does not have 154 a specific scalar was shown. This is a fallback that is used when the code is 155 not properly setting a specific autofill type, and it should not normally be 156 used. If it appears in the data, it means we need to investigate and fix the 157 code that is not properly setting a specific autofill type. 158 - ``autofill_url`` 159 For url type autofill. 160 161 Changelog 162 Firefox 134 163 Legacy ``urlbar.impression.*`` telemetry mirrored to Glean. (See bug 1927093) 164 Firefox 138 165 Legacy ``urlbar.impression.*`` telemetry and Glean ``urlbar.impression.*`` telemetry 166 removed completely. (See bug 1932712) 167 168 urlbar.persistedsearchterms.revert_by_popup_count 169 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 170 171 A uint that is incremented when search terms are persisted in the Urlbar and 172 the Urlbar is reverted to show a full URL due to a PopupNotification. This 173 can happen when a user is on a SERP and permissions are requested, e.g. 174 request access to location. If the popup is persistent and the user did not 175 dismiss it before switching tabs, the popup will reappear when they return to 176 the tab. Thus, when returning to the tab with the persistent popup, this 177 value will be incremented because it should have persisted search terms but 178 instead showed a full URL. 179 180 urlbar.persistedsearchterms.view_count 181 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 182 183 A uint that is incremented when search terms should be persisted in the 184 Urlbar. This will trigger when a user loads a SERP from any SAP that results 185 in the search terms persisting in the Urlbar, as well as switching to a tab 186 containing a SERP that should be persisting the search terms in the Urlbar, 187 regardless of whether a PopupNotification is present. Thus, for every 188 ``revert_by_popup_count``, there should be at least one corresponding 189 ``view_count``. 190 191 urlbar.tips 192 ~~~~~~~~~~~ 193 194 NOTE: This telemetry is no longer collected. See changelog below. 195 196 This is a keyed scalar whose values are uints and are incremented each time a 197 tip result is shown, a tip is picked, and a tip's help button is picked. The 198 keys are: 199 200 - ``intervention_clear-help`` 201 Incremented when the user picks the help button in the clear-history search 202 intervention. 203 - ``intervention_clear-picked`` 204 Incremented when the user picks the clear-history search intervention. 205 - ``intervention_clear-shown`` 206 Incremented when the clear-history search intervention is shown. 207 - ``intervention_refresh-help`` 208 Incremented when the user picks the help button in the refresh-Firefox 209 search intervention. 210 - ``intervention_refresh-picked`` 211 Incremented when the user picks the refresh-Firefox search intervention. 212 - ``intervention_refresh-shown`` 213 Incremented when the refresh-Firefox search intervention is shown. 214 - ``intervention_update_ask-help`` 215 Incremented when the user picks the help button in the update_ask search 216 intervention, which is shown when there's a Firefox update available but the 217 user's preference says we should ask them to download and apply it. 218 - ``intervention_update_ask-picked`` 219 Incremented when the user picks the update_ask search intervention. 220 - ``intervention_update_ask-shown`` 221 Incremented when the update_ask search intervention is shown. 222 - ``intervention_update_refresh-help`` 223 Incremented when the user picks the help button in the update_refresh search 224 intervention, which is shown when the user's browser is up to date but they 225 triggered the update intervention. We show this special refresh intervention 226 instead. 227 - ``intervention_update_refresh-picked`` 228 Incremented when the user picks the update_refresh search intervention. 229 - ``intervention_update_refresh-shown`` 230 Incremented when the update_refresh search intervention is shown. 231 - ``intervention_update_restart-help`` 232 Incremented when the user picks the help button in the update_restart search 233 intervention, which is shown when there's an update and it's been downloaded 234 and applied. The user needs to restart to finish. 235 - ``intervention_update_restart-picked`` 236 Incremented when the user picks the update_restart search intervention. 237 - ``intervention_update_restart-shown`` 238 Incremented when the update_restart search intervention is shown. 239 - ``intervention_update_web-help`` 240 Incremented when the user picks the help button in the update_web search 241 intervention, which is shown when we can't update the browser or possibly 242 even check for updates for some reason, so the user should download the 243 latest version from the web. 244 - ``intervention_update_web-picked`` 245 Incremented when the user picks the update_web search intervention. 246 - ``intervention_update_web-shown`` 247 Incremented when the update_web search intervention is shown. 248 - ``tabtosearch-shown`` 249 Increment when a non-onboarding tab-to-search result is shown, once per 250 engine per engagement. Please note that the number of times non-onboarding 251 tab-to-search results are picked is the sum of all keys in 252 ``urlbar.searchmode.tabtosearch``. Please also note that more detailed 253 telemetry is recorded about both onboarding and non-onboarding tab-to-search 254 results in urlbar.tabtosearch.*. These probes in ``urlbar.tips`` are still 255 recorded because ``urlbar.tabtosearch.*`` is not currently recorded 256 in Release. 257 - ``tabtosearch_onboard-shown`` 258 Incremented when a tab-to-search onboarding result is shown, once per engine 259 per engagement. Please note that the number of times tab-to-search 260 onboarding results are picked is the sum of all keys in 261 ``urlbar.searchmode.tabtosearch_onboard``. 262 - ``searchTip_onboard-picked`` 263 Incremented when the user picks the onboarding search tip. 264 - ``searchTip_onboard-shown`` 265 Incremented when the onboarding search tip is shown. 266 - ``searchTip_redirect-picked`` 267 Incremented when the user picks the redirect search tip. 268 - ``searchTip_redirect-shown`` 269 Incremented when the redirect search tip is shown. 270 271 Changelog 272 Firefox 134 273 Legacy ``urlbar.tips`` telemetry mirrored to Glean. (See bug 1927093) 274 Firefox 137 275 Legacy ``urlbar.tips`` telemetry and Glean ``urlbar.tips`` telemetry 276 removed completely. (See bug 1932716) 277 278 urlbar.searchmode.* 279 ~~~~~~~~~~~~~~~~~~~ 280 281 This is a set of keyed scalars whose values are uints incremented each 282 time search mode is entered in the Urlbar. The suffix on the scalar name 283 describes how search mode was entered. Possibilities include: 284 285 - ``bookmarkmenu`` 286 Used when the user selects the Search Bookmarks menu item in the Library 287 menu. 288 - ``handoff`` 289 Used when the user uses the search box on the new tab page and is handed off 290 to the address bar. NOTE: This entry point was disabled from Firefox 88 to 291 91. Starting with 91, it will appear but in low volume. Users must have 292 searching in the Urlbar disabled to enter search mode via handoff. 293 - ``keywordoffer`` 294 Used when the user selects a keyword offer result. 295 - ``oneoff`` 296 Used when the user selects a one-off engine in the Urlbar. 297 - ``searchbutton`` 298 Used when the user entered search mode via the unified search button. 299 Added in Firefox 133, but the unified search button was not enabled in 300 release until 136. 301 - ``shortcut`` 302 Used when the user enters search mode with a keyboard shortcut or menu bar 303 item (e.g. ``Accel+K``). 304 - ``tabmenu`` 305 Used when the user selects the Search Tabs menu item in the tab overflow 306 menu. 307 - ``tabtosearch`` 308 Used when the user selects a tab-to-search result. These results suggest a 309 search engine when the search engine's domain is autofilled. 310 - ``tabtosearch_onboard`` 311 Used when the user selects a tab-to-search onboarding result. These are 312 shown the first few times the user encounters a tab-to-search result. 313 - ``topsites_newtab`` 314 Used when the user selects a search shortcut Top Site from the New Tab Page. 315 - ``topsites_urlbar`` 316 Used when the user selects a search shortcut Top Site from the Urlbar. 317 - ``touchbar`` 318 Used when the user taps a search shortct on the Touch Bar, available on some 319 Macs. 320 - ``typed`` 321 Used when the user types an engine alias in the Urlbar. 322 - ``historymenu`` 323 Used when the user selects the Search History menu item in a History 324 menu. 325 - ``other`` 326 Used as a catchall for other behaviour. We don't expect this scalar to hold 327 any values. If it does, we need to correct an issue with search mode entry 328 points. 329 330 The keys for the scalars above are engine and source names. If the user enters 331 a remote search mode with a built-in engine, we record the engine name. If the 332 user enters a remote search mode with an engine they installed (e.g. via 333 OpenSearch or a WebExtension), we record ``other`` (not to be confused with 334 the ``urlbar.searchmode.other`` scalar above). 335 336 When a user enters local search mode, we record the English name of the 337 result source (e.g., "bookmarks," "history," "tabs"). If they enter local 338 search mode via ``typed``, we record the result source name with the suffix 339 "keyword" or "symbol," depending on whether the user used a symbol 340 (``^, %, *, >``) or a keyword (``@tabs, @bookmarks, @history, @actions``). 341 If they enter local search mode through ``keywordoffer``, we record the 342 result source name with the suffix "keyword" when they select a restrict 343 keyword. 344 345 Note that we slightly modify the engine name for some built-in engines: we 346 flatten all localized Amazon sites (Amazon.com, Amazon.ca, Amazon.de, etc.) 347 to "Amazon" and we flatten all localized Wikipedia sites (Wikipedia (en), 348 Wikipedia (fr), etc.) to "Wikipedia". This is done to reduce the number of 349 keys used by these scalars. 350 351 Changelog 352 Firefox 132 353 The scalar keys for ``urlbar.searchmode.typed`` and 354 ``urlbar.searchmode.keywordoffer`` have been updated. 355 356 For ``urlbar.searchmode.typed``: 357 - If the user enters local search mode using a restrict keyword (@tabs, 358 @history, @bookmarks, @actions) the scalar key is prefixed with 359 "keyword". 360 - If the user enters via a symbol (``%, ^, *, >``) the key is prefixed 361 with "symbol". 362 363 For example, in history search mode: 364 - If entered via a restrict keyword, the scalar key recorded is 365 ``history_keyword``. 366 - If entered via a symbol, the scalar key recorded is ``history_symbol``. 367 368 For ``urlbar.searchmode.keywordoffer``: 369 - If the user uses a restrict keyword through the keywordoffer method, 370 the scalar key is prefixed with "keyword". 371 372 Please note that symbols cannot trigger the ``urlbar.searchmode.keywordoffer`` 373 telemetry, as symbols are only valid for typed. [Bug `1919180`_] 374 375 Firefox 133 376 Added ``urlbar.searchmode.searchbutton``: 377 - This new probe is for accesses to search mode from the unified search 378 button. The button was released in Firefox 136 and replaced the previous 379 one-off buttons (``urlbar.searchmode.oneoff``). 380 381 Added Glean equivalents of the probes as labeled counters. 382 383 384 urlbar.picked.* 385 ~~~~~~~~~~~~~~~ 386 387 NOTE: This telemetry is no longer collected. See changelog below. 388 389 This is a set of keyed scalars whose values are uints incremented each 390 time a result is picked from the Urlbar. The suffix on the scalar name 391 is the result type. The keys for the scalars above are the 0-based index of 392 the result in the urlbar panel when it was picked. 393 394 .. note:: 395 Available from Firefox 84 on. Use the *FX_URLBAR_SELECTED_** histograms in 396 earlier versions. 397 398 .. note:: 399 Firefox 102 deprecated ``autofill`` and added ``autofill_about``, 400 ``autofill_adaptive``, ``autofill_origin``, ``autofill_other``, 401 ``autofill_preloaded``, and ``autofill_url``. In Firefox 116, 402 ``autofill_preloaded`` was removed. 403 404 Valid result types are: 405 406 - ``autofill`` 407 This scalar was deprecated in Firefox 102 and replaced with 408 ``autofill_about``, ``autofill_adaptive``, ``autofill_origin``, 409 ``autofill_other``, ``autofill_preloaded``, and ``autofill_url``. Previously 410 it was recorded in each of the cases that the other scalars now cover. 411 - ``autofill_about`` 412 An autofilled "about:" page URI (e.g., about:config). The user must first 413 type "about:" to trigger this type of autofill. 414 - ``autofill_adaptive`` 415 An autofilled URL from the user's adaptive history. This type of autofill 416 differs from ``autofill_url`` in two ways: (1) It's based on the user's 417 adaptive history, a particular type of history that associates the user's 418 search string with the URL they pick in the address bar. (2) It autofills 419 full URLs instead of "up to the next slash" partial URLs. For more 420 information on this type of autofill, see this `adaptive history autofill 421 document`_. 422 - ``autofill_origin`` 423 An autofilled origin_ from the user's history. Typically "origin" means a 424 domain or host name like "mozilla.org". Technically it can also include a 425 URL scheme or protocol like "https" and a port number like ":8000". Firefox 426 can autofill domain names by themselves, domain names with schemes, domain 427 names with ports, and domain names with schemes and ports. All of these 428 cases count as origin autofill. For more information, see this `adaptive 429 history autofill document`_. 430 - ``autofill_other`` 431 Counts how many times some other type of autofill result that does not have 432 a specific keyed scalar was picked at a given index. This is a fallback that 433 is used when the code is not properly setting a specific autofill type, and 434 it should not normally be used. If it appears in the data, it means we need 435 to investigate and fix the code that is not properly setting a specific 436 autofill type. 437 - ``autofill_url`` 438 An autofilled URL or partial URL from the user's history. Firefox autofills 439 URLs "up to the next slash", so to trigger URL autofill, the user must first 440 type a domain name (or trigger origin autofill) and then begin typing the 441 rest of the URL (technically speaking, its path). As they continue typing, 442 the URL will only be partially autofilled up to the next slash, or if there 443 is no next slash, to the end of the URL. This allows the user to easily 444 visit different subpaths of a domain. For more information, see this 445 `adaptive history autofill document`_. 446 - ``bookmark`` 447 A bookmarked URL. 448 - ``bookmark_adaptive`` 449 A bookmarked URL retrieved from adaptive history. 450 - ``clipboard`` 451 A URL retrieved from the system clipboard. 452 - ``dynamic`` 453 A specially crafted result, often used in experiments when basic types are 454 not flexible enough for a rich layout. 455 - ``dynamic_wikipedia`` 456 A dynamic Wikipedia Firefox Suggest result. 457 - ``extension`` 458 Added by an add-on through the omnibox WebExtension API. 459 - ``formhistory`` 460 A search suggestion from previous search history. 461 - ``history`` 462 A URL from history. 463 - ``history_adaptive`` 464 A URL from history retrieved from adaptive history. 465 - ``keyword`` 466 A bookmark keyword. 467 - ``navigational`` 468 A navigational suggestion Firefox Suggest result. 469 - ``quickaction`` 470 A QuickAction. 471 - ``quicksuggest`` 472 A Firefox Suggest (a.k.a. quick suggest) suggestion. 473 - ``remotetab`` 474 A tab synced from another device. 475 - ``restrict_keyword_actions`` 476 A restrict keyword result to enter search mode for actions. 477 - ``restrict_keyword_bookmarks`` 478 A restrict keyword result to enter search mode for bookmarks. 479 - ``restrict_keyword_history`` 480 A restrict keyword result to enter search mode for history. 481 - ``restrict_keyword_tabs`` 482 A restrict keyword result to enter search mode for tabs. 483 - ``searchengine`` 484 A search result, but not a suggestion. May be the default search action 485 or a search alias. 486 - ``searchsuggestion`` 487 A remote search suggestion. 488 - ``switchtab`` 489 An open tab. 490 - ``tabtosearch`` 491 A tab to search result. 492 - ``tip`` 493 A tip result. 494 - ``topsite`` 495 An entry from top sites. 496 - ``trending`` 497 A trending suggestion. 498 - ``unknown`` 499 An unknown result type, a bug should be filed to figure out what it is. 500 - ``visiturl`` 501 The user typed string can be directly visited. 502 - ``weather`` 503 A Firefox Suggest weather suggestion. 504 505 .. _adaptive history autofill document: https://docs.google.com/document/d/e/2PACX-1vRBLr_2dxus-aYhZRUkW9Q3B1K0uC-a0qQyE3kQDTU3pcNpDHb36-Pfo9fbETk89e7Jz4nkrqwRhi4j/pub 506 .. _origin: https://html.spec.whatwg.org/multipage/origin.html#origin 507 508 Changelog 509 Firefox 134 510 Legacy ``urlbar.picked`` telemetry mirrored to Glean. (See bug 1927093) 511 Firefox 137 512 Legacy ``urlbar.picked`` telemetry and Glean ``urlbar.picked`` telemetry 513 removed completely. (See bug 1932713) 514 515 urlbar.picked.searchmode.* 516 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 517 518 NOTE: This telemetry is no longer collected. See changelog below. 519 520 This is a set of keyed scalars whose values are uints incremented each time a 521 result is picked from the Urlbar while the Urlbar is in search mode. The 522 suffix on the scalar name is the search mode entry point. The keys for the 523 scalars are the 0-based index of the result in the urlbar panel when it was 524 picked. 525 526 .. note:: 527 These scalars share elements of both ``urlbar.picked.*`` and 528 ``urlbar.searchmode.*``. Scalar name suffixes are search mode entry points, 529 like ``urlbar.searchmode.*``. The keys for these scalars are result indices, 530 like ``urlbar.picked.*``. 531 532 .. note:: 533 These data are a subset of the data recorded by ``urlbar.picked.*``. For 534 example, if the user enters search mode by clicking a one-off then selects 535 a Google search suggestion at index 2, we would record in **both** 536 ``urlbar.picked.searchsuggestion`` and ``urlbar.picked.searchmode.oneoff``. 537 538 Changelog 539 Firefox 134 540 Legacy ``urlbar.picked.searchmode`` telemetry mirrored to Glean. (See 541 bug 1927093) 542 Firefox 137 543 Legacy ``urlbar.picked.searchmode`` telemetry and Glean 544 ``urlbar.picked.searchmode`` telemetry removed completely. (See 545 bug 1932713) 546 547 urlbar.tabtosearch.* 548 ~~~~~~~~~~~~~~~~~~~~ 549 550 NOTE: This telemetry is no longer collected. See changelog below. 551 552 This is a set of keyed scalars whose values are uints incremented when a 553 tab-to-search result is shown, once per engine per engagement. There are two 554 sub-probes: ``urlbar.tabtosearch.impressions`` and 555 ``urlbar.tabtosearch.impressions_onboarding``. The former records impressions 556 of regular tab-to-search results and the latter records impressions of 557 onboarding tab-to-search results. The key values are identical to those of the 558 ``urlbar.searchmode.*`` probes: they are the names of the engines shown in the 559 tab-to-search results. Engines that are not built in are grouped under the 560 key ``other``. 561 562 .. note:: 563 Due to the potentially sensitive nature of these data, they are currently 564 collected only on pre-release version of Firefox. See bug 1686330. 565 566 Changelog 567 Firefox 134 568 Legacy ``urlbar.tabtosearch.*`` telemetry mirrored to Glean. (See 569 bug 1927093) 570 Firefox 137 571 Legacy ``urlbar.tabtosearch.*`` telemetry and Glean 572 ``urlbar.tabtosearch.*`` telemetry removed completely. (See bug 1932715) 573 574 urlbar.zeroprefix.abandonment 575 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 576 577 A uint recording the number of abandonments of the zero-prefix view. 578 "Zero-prefix" means the search string was empty, so the zero-prefix view is 579 the view that's shown when the user clicks in the urlbar before typing a 580 search string. Often it's called the "top sites" view since normally it shows 581 the user's top sites. "Abandonment" means the user opened the zero-prefix view 582 but it was closed without the user picking a result inside it. This scalar was 583 introduced in Firefox 110.0 in bug 1806765. 584 585 urlbar.zeroprefix.engagement 586 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 587 588 A uint recording the number of engagements in the zero-prefix view. 589 "Zero-prefix" means the search string was empty, so the zero-prefix view is 590 the view that's shown when the user clicks in the urlbar before typing a 591 search string. Often it's called the "top sites" view since normally it shows 592 the user's top sites. "Engagement" means the user picked a result inside the 593 view. This scalar was introduced in Firefox 110.0 in bug 1806765. 594 595 urlbar.zeroprefix.exposure 596 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 597 598 A uint recording the number of times the user was exposed to the zero-prefix 599 view; that is, the number of times it was shown. "Zero-prefix" means the 600 search string was empty, so the zero-prefix view is the view that's shown when 601 the user clicks in the urlbar before typing a search string. Often it's called 602 the "top sites" view since normally it shows the user's top sites. This scalar 603 was introduced in Firefox 110.0 in bug 1806765. 604 605 urlbar.quickaction.picked 606 ~~~~~~~~~~~~~~~~~~~~~~~~~ 607 608 A uint recording the number of times the user selected a quickaction, the 609 key is in the form $key-$n where $n is the number of characters the user typed 610 in order for the suggestion to show. See bug 1783155. 611 612 urlbar.unifiedsearchbutton.opened 613 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 614 615 A uint recording the number of times the user opens search mode popup via 616 Unified Search Button. 617 See bug 1936673. 618 619 urlbar.unifiedsearchbutton.picked 620 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 621 622 A uint recording the number of times the user selected a search mode via 623 Unified Search Button. See bug 1936673. 624 625 places.* 626 ~~~~~~~~ 627 628 This is Places related telemetry. 629 630 Valid result types are: 631 632 - ``sponsored_visit_no_triggering_url`` 633 Number of sponsored visits that could not find their triggering URL in 634 history. We expect this to be a small number just due to the navigation layer 635 manipulating URLs. A large or growing value may be a concern. 636 - ``pages_need_frecency_recalculation`` 637 Number of pages in need of a frecency recalculation. This number should 638 remain small compared to the total number of pages in the database (see the 639 `PLACES_PAGES_COUNT` histogram). It can be used to valuate the frequency 640 and size of recalculations, for performance reasons. 641 642 Search Engagement Telemetry 643 --------------------------- 644 645 The search engagement telemetry provided since Firefox 110 is is recorded using 646 Glean events. Please see the following documents for the details. 647 648 - `Engagement`_ : 649 It is defined as a completed action in urlbar, where a user picked one of 650 the results. 651 - `Abandonment`_ : 652 It is defined as an action where the user open the results but does not 653 complete an engagement action, usually unfocusing the urlbar. This also 654 happens when the user switches to another window, if the results popup was 655 opening. 656 657 .. _Engagement: https://dictionary.telemetry.mozilla.org/apps/firefox_desktop/metrics/urlbar_engagement 658 .. _Abandonment: https://dictionary.telemetry.mozilla.org/apps/firefox_desktop/metrics/urlbar_abandonment 659 660 Changelog 661 Firefox 141 662 New result types have been added, in particular sub-types can now be added 663 to `history` and `tab`, indicating whether they are from semantic history, 664 or SERP, e.g. `history_serp`, `history_semantic`, `tab_semantic_serp`. 665 [Bug `1971534`_] 666 667 Firefox 128 668 The "actions" key was added to the engagement event. [Bug `1893067`_] 669 670 Firefox 125 671 The "impression" engagement event has been removed. [Bug `1878983`_] 672 673 .. _1971534: https://bugzilla.mozilla.org/show_bug.cgi?id=1971534 674 .. _1893067: https://bugzilla.mozilla.org/show_bug.cgi?id=1893067 675 .. _1878983: https://bugzilla.mozilla.org/show_bug.cgi?id=1878983 676 677 678 Custom pings for Contextual Services 679 ------------------------------------ 680 681 Contextual Services currently has two features involving the address bar, top 682 sites and Firefox Suggest. Top sites telemetry is sent in the `"top-sites" ping`_, 683 which is described in the linked Glean Dictionary page. For Firefox 684 Suggest, see the :doc:`firefox-suggest-telemetry` document. 685 686 .. _"top-sites" ping: https://mozilla.github.io/glean/book/user/pings/custom.html 687 688 Changelog 689 Firefox 122.0 690 PingCentre-sent custom pings removed. [Bug `1868580`_] 691 692 Firefox 116.0 693 The "top-sites" ping is implemented. [Bug `1836283`_] 694 695 .. _1868580: https://bugzilla.mozilla.org/show_bug.cgi?id=1868580 696 .. _1836283: https://bugzilla.mozilla.org/show_bug.cgi?id=1836283 697 698 699 Other telemetry relevant to the Address Bar 700 ------------------------------------------- 701 702 Search Telemetry 703 ~~~~~~~~~~~~~~~~ 704 705 Some of `the search telemetry`_ is also relevant to the address bar. 706 707 contextual.services.topsites.* 708 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 709 710 These keyed scalars instrument the impressions and clicks for sponsored top 711 sites in the urlbar. 712 The key is a combination of the source and the placement of the top sites link 713 (1-based) such as 'urlbar_1'. For each key, it records the counter of the 714 impression or click. 715 Note that these scalars are shared with the top sites on the newtab page. 716 717 Telemetry Environment 718 ~~~~~~~~~~~~~~~~~~~~~ 719 720 The following preferences relevant to the address bar are recorded in 721 :doc:`telemetry environment data </toolkit/components/telemetry/data/environment>`: 722 723 - ``browser.search.suggest.enabled``: The global toggle for search 724 suggestions everywhere in Firefox (search bar, urlbar, etc.). Defaults to 725 true. 726 - ``browser.urlbar.autoFill``: The global preference for whether autofill in 727 the urlbar is enabled. When false, all types of autofill are disabled. 728 - ``browser.urlbar.autoFill.adaptiveHistory.enabled``: True if adaptive 729 history autofill in the urlbar is enabled. 730 - ``browser.urlbar.suggest.searches``: True if search suggestions are 731 enabled in the urlbar. Defaults to false. 732 733 Firefox Suggest 734 ~~~~~~~~~~~~~~~ 735 736 Telemetry specific to Firefox Suggest is described in the 737 :doc:`firefox-suggest-telemetry` document. 738 739 .. _the search telemetry: /browser/search/telemetry.html 740 .. _1919180: https://bugzilla.mozilla.org/show_bug.cgi?id=1919180