Bug 1302681 - Part 3: Update documentation to cover dynamic events. r=dexter, a=lizzard
authorGeorg Fritzsche <georg.fritzsche@googlemail.com>
Thu, 27 Jul 2017 07:19:00 -0400
changeset 423525 e3682dd9a9cb9cd02bc3d61770b3bc24d884d0fe
parent 423524 a66c7da43621e6e5b877ad8cab1ad95ba5bdba9c
child 423526 edbb6431090cb9e791750c2c5fee1363a788449c
push id1517
push userjlorenzo@mozilla.com
push dateThu, 14 Sep 2017 16:50:54 +0000
treeherdermozilla-release@3b41fd564418 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersdexter, lizzard
bugs1302681
milestone56.0
Bug 1302681 - Part 3: Update documentation to cover dynamic events. r=dexter, a=lizzard
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.