Bug 1302681 - Part 3: Update documentation to cover dynamic events. r=Dexter
☠☠ backed out by 89d41dea4847 ☠ ☠
authorGeorg Fritzsche <georg.fritzsche@googlemail.com>
Thu, 27 Jul 2017 07:19:00 -0400
changeset 420286 9c0bdff48a0ac1359bad997a080019436b1b6cd2
parent 420285 8e79158a7a1c3d15ec8415c1810f9c7dfd675cf3
child 420287 69371361c3f98ea2f552b6baf5e6bd2d9c91d87e
push id7566
push usermtabara@mozilla.com
push dateWed, 02 Aug 2017 08:25:16 +0000
treeherdermozilla-beta@86913f512c3c [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersDexter
bugs1302681
milestone56.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1302681 - Part 3: Update documentation to cover dynamic events. r=Dexter
toolkit/components/telemetry/docs/collection/events.rst
--- a/toolkit/components/telemetry/docs/collection/events.rst
+++ b/toolkit/components/telemetry/docs/collection/events.rst
@@ -61,17 +61,17 @@ For the Firefox Telemetry implementation
 - ``extra``: Max. number of keys is ``10``.
   - Each extra key name: Max. string length is ``15``.
   - Each extra value: Max. byte length is ``80``.
 
 The YAML definition file
 ========================
 
 Any event recorded into Firefox Telemetry must be registered before it can be recorded.
-This happens in `Events.yaml <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Events.yaml>`_.
+For any code that ships as part of Firefox that happens in `Events.yaml <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Events.yaml>`_.
 
 The probes in the definition file are represented in a fixed-depth, three-level structure. The first level contains *category* names (grouping multiple events together), the second level contains *event* names, under which the events properties are listed. E.g.:
 
 .. code-block:: yaml
 
   # The following is a category of events named "browser.ui".
   browser.ui:
     click: # This is the event named "click".
@@ -150,33 +150,73 @@ Example:
   // event: [543345, "ui", "click", "reload-btn"]
   Services.telemetry.recordEvent("ui", "search", "search-bar", "google");
   // event: [89438, "ui", "search", "search-bar", "google"]
   Services.telemetry.recordEvent("ui", "completion", "search-bar", "yahoo",
                                  {"querylen": "7", "results": "23"});
   // event: [982134, "ui", "completion", "search-bar", "yahoo",
   //           {"qerylen": "7", "results": "23"}]
 
+``setEventRecordingEnabled()``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 .. code-block:: js
 
   Services.telemetry.setEventRecordingEnabled(category, enabled);
 
 Event recording is currently disabled by default. Privileged addons and Firefox code can enable & disable recording events for specific categories using this function.
 
 Example:
 
 .. code-block:: js
 
   Services.telemetry.setEventRecordingEnabled("ui", true);
   // ... now events in the "ui" category will be recorded.
   Services.telemetry.setEventRecordingEnabled("ui", false);
   // ... now "ui" events will not be recorded anymore.
 
+``registerEvents()``
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: js
+
+  Services.telemetry.registerEvents(category, eventData);
+
+Register new events from add-ons.
+
+* ``category`` - *(required, string)* The category the events are in.
+* ``eventData`` - *(required, object)* An object of the form ``{eventName1: event1Data, ...}``, where each events data is an object with the entries:
+
+  * ``methods`` - *(required, list of strings)* The valid event methods.
+  * ``objects`` - *(required, list of strings)* The valid event objects.
+  * ``extra_keys`` - *(optional, list of strings)* The valid extra keys for the event.
+  * ``record_on_release`` - *(optional, bool)*
+
+For events recorded from add-ons, registration happens at runtime. Any new events must first be registered through this function before they can be recorded.
+The registered categories will automatically be enabled for recording.
+
+After registration, the events can be recorded through the ``recordEvent()`` function. They will be submitted in the main pings payload under ``processes.dynamic.events``.
+
+New events registered here are subject to the same limitations as the ones registered through ``Events.yaml``, although the naming was in parts updated to recent policy changes.
+
+Example:
+
+.. code-block:: js
+
+  Services.telemetry.registerEvents("myAddon.interaction", {
+    "click": {
+      methods: ["click"],
+      objects: ["red_button", "blue_button"],
+    }
+  });
+  // Now events can be recorded.
+  Services.telemetry.recordEvent("myAddon.interaction", "click", "red_button");
+
 Internal API
-~~~~~~~~~~~~
+------------
 
 .. code-block:: js
 
   Services.telemetry.snapshotEvents(dataset, clear);
   Services.telemetry.clearEvents();
 
 These functions are only supposed to be used by Telemetry internally or in tests.