diff options
Diffstat (limited to 'toolkit/components/telemetry/docs/collection/user-interactions.rst')
| -rw-r--r-- | toolkit/components/telemetry/docs/collection/user-interactions.rst | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/toolkit/components/telemetry/docs/collection/user-interactions.rst b/toolkit/components/telemetry/docs/collection/user-interactions.rst new file mode 100644 index 0000000000..16d1d53977 --- /dev/null +++ b/toolkit/components/telemetry/docs/collection/user-interactions.rst @@ -0,0 +1,272 @@ +.. _userinteractionstelemetry: + +================= +User Interactions +================= + +The Background Hang Reporter is a tool that collects stacks during hangs on pre-release channels. +User Interactions are a way of annotating Background Hang Reports with additional information about what the user was doing when a hang occurs. +This allows for grouping and prioritization of hangs based on the user interactions that they occur during. + +Since the built-in profiler is often the first tool that developers reach for to debug performance issues, +User Interactions also will add profiler markers for each recording. + +.. important:: + + Every new or changed data collection in Firefox needs a `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection>`__ from a Data Steward. + +.. _userinteractionsserializationformat: + +Serialization format +==================== + +User Interactions are submitted in a :doc:`../data/backgroundhangmonitor-ping` as a property under the `annotations` for a hang, e.g.: + +.. code-block:: js + + ... + { + "duration": 105.547582, + // ... + "annotations": [ + ["UserInteracting", "true"] + ["browser.tabs.opening", "animated"] + ], + "stack": [ + "XREMain::XRE_main", + "-[GeckoNSApplication nextEventMatchingMask:untilDate:inMode:dequeue:]", + "nsAppShell::ProcessGeckoEvents", + "nsRefreshDriver::Tick", + "EventDispatcher::Dispatch", + "EventDispatcher::Dispatch", + "", + "browser/content/tabbrowser-tabs.js:1699", + "browser/content/tabbrowser-tabs.js:1725", + "browser/content/tabbrowser-tabs.js:142", + "browser/content/tabbrowser-tabs.js:153", + "(jit frame)", + "(unresolved)", + [ + 1, + "418de17" + ], + [ + 1, + "418de91" + ], + [ + 1, + "4382e56" + ], + [ + 8, + "108e3" + ], + [ + 9, + "2624" + ], + [ + 9, + "129f" + ] + ] + // ... + }, + +Each User Interaction is of the form: + +.. code-block:: js + + ["User Interaction ID", "value"] + +A `User Interaction ID` is its category concatenated with its name. +For example, a User Interaction with category `browser.tabs` and name `opening` has an ID of `browser.tabs.opening`. + +.. _userinteractionslimits: + +Limits +------ + +Each ``String`` marked as an identifier (the User Interaction ``name``, ``category``, ``value``) is restricted to be composed of alphanumeric ASCII characters ([a-zA-Z0-9]) plus infix underscores ('_' characters that aren't the first or last). +``category`` is also permitted infix periods ('.' characters, so long as they aren't the first or last character). + +Several fields are subject to length limits: + +- ``category``: Max. byte length is ``40``. +- ``User Interaction`` name: Max. byte length is ``40``. +- ``value``: A UTF-8 string with max. byte length of ``50``. + +Any ``String`` going over its limit will be reported as an error and the operation aborted. + + +.. _userinteractionsdefinition: + +The YAML definition file +======================== + +Any User Interaction recorded into Firefox Telemetry must be registered before it can be recorded. +For any code that ships as part of Firefox that happens in `UserInteractions.yaml <https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/UserInteractions.yaml>`_. + +The User Interactions in the definition file are represented in a fixed-depth, three-level structure. +The first level contains *category* names (grouping multiple User Interactions together), +the second level contains User Interaction IDs, under which the User Interaction properties are listed. E.g.: + +.. code-block:: yaml + + # The following is a category of User Interactions named "browser.tabs". + browser.tabs: + opening: # This is the name of the User Interaction. The ID for the + # User Interaction is browser.tabs.opening + description: > + Describes this User Interaction in detail, potentially over + multiple lines. + # ... and more User Interaction properties. + # ... and more User Interactions. + # This is the "browser.places" category. + browser.places: + # And the "history" search User Interaction. Its User Interaction ID is + # browser.places.history_async + history_async: + # ... + description: Session History is searched asynchronously. + # ... and more User Interaction properties. + # ... + +Category and User Interaction names are subject to the limits :ref:`specified above <userinteractionslimits>`. + + +Profiler markers +================ + +The profiler markers automatically added for each User Interaction will have a starting point and ending point corresponding with the recording of the User Interaction. +The name of the marker will be the User Interaction category plus the User Interaction ID. +The value of the marker will be the value passed through the `UserInteraction` API, plus any additional text that is optionally added when the recording is finished. + +Further details on what the profiler is and what profiler markers are can be found `here <https://profiler.firefox.com/docs/#/>`_. + + +The API +======= + +Public JS API +------------- + +This API is main-thread only, and all functions will return `false` if accessed off of the main thread. + +``start()`` +~~~~~~~~~~~~~~~~~ + +.. code-block:: js + + UserInteraction.start(id, value, object); + +Starts recording a User Interaction. +Any hangs that occur on the main thread while recording this User Interaction result in an annotation being added to the background hang report. + +If a pre-existing UserInteraction already exists with the same ``id`` and the same ``object``, that pre-existing UserInteraction will be overwritten. +The newly created UserInteraction will include a "(clobbered)" suffix on its BHR annotation name. + +* ``id``: Required. A string value, limited to 80 characters. This is the category name concatenated with the User Interaction name. +* ``value``: Required. A string value, limited to 50 characters. +* ``object``: Optional. If specified, the User Interaction is associated with this object, so multiple recordings can be done concurrently. + +Example: + +.. code-block:: js + + UserInteraction.start("browser.tabs.opening", "animated", window1); + UserInteraction.start("browser.tabs.opening", "animated", window2); + +Returns `false` and logs a message to the browser console if the recording does not start for some reason. + +Example: + +.. code-block:: js + + UserInteraction.start("browser.tabs.opening", "animated", window); + UserInteraction.start("browser.places.history_search", "synchronous"); + +``update()`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: js + + UserInteraction.update(id, value, object); + +Updates a User Interaction that's already being recorded with a new value. +Any hangs that occur on the main thread will be annotated using the new value. +Updating only works for User Interactions that are already being recorded. + +* ``id``: Required. A string value, limited to 80 characters. This is the category name concatenated with the User Interaction name. +* ``value``: Required. The new string value, limited to 50 characters. +* ``object``: Optional. If specified, the User Interaction is associated with this object, so multiple recordings can be done concurrently. + +Returns `false` and logs a message to the browser console if the update cannot be done for some reason. + + +Example: + +.. code-block:: js + + // At this point, we don't know if the tab will open with animation + // or not. + UserInteraction.start("browser.tabs.opening", "initting", window); + // ... + if (animating) { + UserInteraction.update("browser.tabs.opening", "animating", window); + } else { + UserInteraction.update("browser.tabs.opening", "not-animating", window); + } + +``cancel()`` +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: js + + UserInteraction.cancel(id, object); + +Cancels a recording User Interaction. +No profiler marker will be added in this case, and no further hangs will be annotated. +Hangs that occurred before the User Interaction was cancelled will not, however, be expunged. + +* ``id``: Required. A string value, limited to 80 characters. This is the category name concatenated with the User Interaction name. +* ``object``: Optional. If specified, the User Interaction is associated with this object, so multiple recordings can be done concurrently. + +Returns `false` and logs a message to the browser console if the cancellation cannot be completed for some reason. + +``running()`` +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: js + + UserInteraction.running(id, object); + +Checks to see if a UserInteraction is already running. + +* ``id``: Required. A string value, limited to 80 characters. This is the category name concatenated with the User Interaction name. +* ``object``: Optional. If specified, the User Interaction is associated with this object, so multiple recordings can be done concurrently. If you're checking for a running timer that was started with an object, you'll need to pass in that same object here to check its running state. + +Returns `true` if a UserInteraction is already running. + +``finish()`` +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: js + + UserInteraction.finish(id, object, additionalText); + +Finishes recording the User Interaction. +Any hangs that occur on the main thread will no longer be annotated with this User Interaction. +A profiler marker will also be added, starting at the `UserInteraction.start` point and ending at the `UserInteraction.finish` point, along with any additional text that the author wants to include. + +* ``id``: Required. A string value, limited to 80 characters. This is the category name concatenated with the User Interaction name. +* ``object``: Optional. If specified, the User Interaction is associated with this object, so multiple recordings can be done concurrently. +* ``additionalText``: Optional. If specified, the profile marker will have this text appended to the `value`, separated with a comma. + +Returns `false` and logs a message to the browser console if finishing cannot be completed for some reason. + +Version History +=============== + +- Firefox 84: Initial User Interaction support (see `bug 1661304 <https://bugzilla.mozilla.org/show_bug.cgi?id=1661304>`__). |