Adding upstream version 115.7.0esr.upstream/115.7.0esr

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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>`__).