Bug 1313326 - Part 6: Update event documentation. r=dexter
☠☠ backed out by f8cfad560185 ☠ ☠
authorGeorg Fritzsche <georg.fritzsche@googlemail.com>
Tue, 28 Feb 2017 13:39:06 +0100
changeset 345333 e2395b3b1e16f0631700f917bdac5633132be68d
parent 345332 49a7a91b73ccf43451e9da4c5d78792d5ef30837
child 345334 da17b80bf276fc131c18d438233f2bed7ef6f742
push id87558
push userryanvm@gmail.com
push dateWed, 01 Mar 2017 17:06:44 +0000
treeherdermozilla-inbound@e2395b3b1e16 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
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 1313326 - Part 6: Update event documentation. r=dexter
--- a/toolkit/components/telemetry/docs/collection/events.rst
+++ b/toolkit/components/telemetry/docs/collection/events.rst
@@ -91,16 +91,24 @@ The probes in the definition file are re
 Category and probe names are subject to the limits and regex patterns :ref:`specified above <eventlimits>`.
 The following event properties are valid:
 - ``methods`` *(optional, list of strings)*: The valid event methods. If not set this defaults to ``[eventName]``.
 - ``objects`` *(required, list of strings)*: The valid event objects.
 - ``description`` *(required, string)*: Description of the event and its semantics.
 - ``release_channel_collection`` *(optional, string)*: This can be set to ``opt-in`` (default) or ``opt-out``.
+- ``record_in_processes`` *(required, list of strings)*: A list of processes the event can be recorded in. Currently supported values are:
+  - ``main``
+  - ``content``
+  - ``gpu``
+  - ``all_child`` (record in all the child processes)
+  - ``all`` (record in all the processes).
 - ``bug_numbers`` *(required, list of numbers)*: A list of bugzilla bug numbers that are relevant to this event.
 - ``notification_emails`` *(required, list of strings)*: A list of emails of owners for this event. This is used for contact for data reviews and potentially to email alerts.
 - expiry: There are two properties that can specify expiry, at least one needs to be set:
   - ``expiry_version`` *(string)*: The version number in which the event expires, e.g. ``"50"``, or ``"never"``. A version number of type "N" and "N.0" is automatically converted to "N.0a1" in order to expire the event also in the development channels. For events that never expire the value ``never`` can be used.
   - ``expiry_date`` *(date)*: A date of the format ``2014-01-28``. If the local client clock reaches this date, the event will expire and not be recorded.
 - ``extra_keys`` *(optional, object)*: An object that specifies valid keys for the ``extra`` argument and a description - see the example above.
@@ -121,18 +129,16 @@ Public JS API
 Record a registered event.
 * ``value``: Optional, may be ``null``. A string value, limitted to 80 bytes.
 * ``extra``: Optional. An object with string keys & values. Key strings are limitted to what was registered. Value strings are limitted to 80 bytes.
 Throws if the combination of ``category``, ``method`` and ``object`` is unknown.
 Recording an expired event will not throw, but print a warning into the browser console.
-Note: Currently events are only recorded in the main process. Recording in other processes is silently ignored (until `bug 1313326 <https://bugzilla.mozilla.org/show_bug.cgi?id=1313326>`_ is landed).
 .. code-block:: js
   Services.telemetry.recordEvent("ui", "click", "reload-btn");
   // event: [543345, "ui", "click", "reload-btn"]
   Services.telemetry.recordEvent("ui", "search", "search-bar", "google");
   // event: [89438, "ui", "search", "search-bar", "google"]
@@ -160,8 +166,15 @@ Internal API
 .. code-block:: js
   Services.telemetry.snapshotBuiltinEvents(dataset, clear);
 These functions are only supposed to be used by Telemetry internally or in tests.
+Version History
+- Firefox 52: Initial event support (`bug 1302663 <https://bugzilla.mozilla.org/show_bug.cgi?id=1302663>`_).
+- Firefox 53: Event recording disabled by default (`bug 1329139 <https://bugzilla.mozilla.org/show_bug.cgi?id=1329139>`_).
+- Firefox 54: Added child process events (`bug 1313326 <https://bugzilla.mozilla.org/show_bug.cgi?id=1313326>`_).
--- a/toolkit/components/telemetry/docs/data/main-ping.rst
+++ b/toolkit/components/telemetry/docs/data/main-ping.rst
@@ -118,16 +118,17 @@ Structure:
         keyedScalars: {...},
         events: {...},
       "content": {
         scalars: {...},
         keyedScalars: {...},
         histograms: {...},
         keyedHistograms: {...},
+        events: {...},
       "gpu": {
         // ...
 histograms and keyedHistograms