Bug 1486792 - Generate docs for WebExtension Telemetry API r=chutten
authorJan-Erik Rediger <jrediger@mozilla.com>
Thu, 24 Jan 2019 20:09:51 +0000
changeset 515417 733f8ca84534b177d2291e4b507a0a70bcc7dc3b
parent 515416 50017809b1742e1fc77893e7dc6ffec6ca6e5f94
child 515418 2a05e7932e637ebf73ce13dc56175e8a69152839
push id1953
push userffxbld-merge
push dateMon, 11 Mar 2019 12:10:20 +0000
treeherdermozilla-release@9c35dcbaa899 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewerschutten
bugs1486792
milestone66.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 1486792 - Generate docs for WebExtension Telemetry API r=chutten Based on the documentation in toolkit/components/extensions/schemas/telemetry.json. Generated using a Ruby script: https://gist.github.com/badboy/858d5fddc814ca15161d327d6e35b149 Small manual changes after initial import (e.g. adding default values, linking and some phrasing) Differential Revision: https://phabricator.services.mozilla.com/D17247
toolkit/components/extensions/schemas/telemetry.json
toolkit/components/telemetry/docs/collection/custom-pings.rst
toolkit/components/telemetry/docs/collection/events.rst
toolkit/components/telemetry/docs/collection/index.rst
toolkit/components/telemetry/docs/collection/scalars.rst
toolkit/components/telemetry/docs/collection/webextension-api.rst
--- a/toolkit/components/extensions/schemas/telemetry.json
+++ b/toolkit/components/extensions/schemas/telemetry.json
@@ -134,17 +134,17 @@
             }
           }
         }
       ]
     },
     {
       "name": "canUpload",
       "type": "function",
-      "description": "Checks if Telemetry is enabled.",
+      "description": "Checks if Telemetry upload is enabled.",
       "parameters": [],
       "async": true
     },
     {
       "name": "scalarAdd",
       "type": "function",
       "description": "Adds the value to the given scalar.",
       "async": true,
--- a/toolkit/components/telemetry/docs/collection/custom-pings.rst
+++ b/toolkit/components/telemetry/docs/collection/custom-pings.rst
@@ -1,8 +1,10 @@
+.. _submitting-customping:
+
 =======================
 Submitting custom pings
 =======================
 
 Custom pings can be submitted from JavaScript using:
 
 .. code-block:: js
 
--- a/toolkit/components/telemetry/docs/collection/events.rst
+++ b/toolkit/components/telemetry/docs/collection/events.rst
@@ -207,16 +207,18 @@ Example:
   Services.telemetry.setEventRecordingEnabled("ui", false);
   // ... now "ui" events will not be recorded anymore.
 
 .. note::
 
   Even if your event category isn't enabled, counts of events that attempted to be recorded will
   be :ref:`summarized <events.event-summary>`.
 
+.. _registerevents:
+
 ``registerEvents()``
 ~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: js
 
   Services.telemetry.registerEvents(category, eventData);
 
 Register new events from add-ons.
--- a/toolkit/components/telemetry/docs/collection/index.rst
+++ b/toolkit/components/telemetry/docs/collection/index.rst
@@ -18,16 +18,17 @@ The current data collection possibilitie
 * :doc:`events` can record richer data on individual occurrences of specific actions
 * :doc:`measuring elapsed time <measuring-time>`
 * :doc:`custom pings <custom-pings>`
 * :doc:`stack capture <stack-capture>` allow recording application call stacks
 * :doc:`Use counters <use-counters>` measure the usage of web platform features
 * :doc:`Experiment annotations <experiments>`
 * :doc:`Remote content uptake <uptake>`
 * :doc:`Hybrid Content Telemetry <hybrid-content>` allows recording telemetry from semi-privileged hosted content
+* :doc:`WebExtension API <webextension-api>` can be used in privileged webextensions
 
 .. toctree::
    :maxdepth: 2
    :titlesonly:
    :hidden:
    :glob:
 
    scalars
--- a/toolkit/components/telemetry/docs/collection/scalars.rst
+++ b/toolkit/components/telemetry/docs/collection/scalars.rst
@@ -29,16 +29,18 @@ Probes in privileged JavaScript code can
   Services.telemetry.keyedScalarAdd(aName, aKey, aValue);
   Services.telemetry.keyedScalarSet(aName, aKey, aValue);
   Services.telemetry.keyedScalarSetMaximum(aName, aKey, aValue);
 
 These functions can throw if, for example, an operation is performed on a scalar type that doesn't support it
 (e.g. calling scalarSetMaximum on a scalar of the string kind). Please look at the `code documentation <https://dxr.mozilla.org/mozilla-central/search?q=regexp%3ATelemetryScalar%3A%3A(Set%7CAdd)+file%3ATelemetryScalar.cpp&redirect=false>`_ for
 additional information.
 
+.. _registerscalars:
+
 ``registerScalars()``
 ~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: js
 
   Services.telemetry.registerScalars(category, scalarData);
 
 Register new scalars from add-ons.
new file mode 100644
--- /dev/null
+++ b/toolkit/components/telemetry/docs/collection/webextension-api.rst
@@ -0,0 +1,158 @@
+.. _webextension-telemetry:
+
+==============================
+WebExtension API for Telemetry
+==============================
+
+Use the ``browser.telemetry`` API to send telemetry data to the Mozilla Telemetry service. Restricted to Mozilla privileged webextensions.
+
+Types
+-----
+
+``ScalarType``
+~~~~~~~~~~~~~~
+
+Type of scalar: 'count' for numeric values, 'string' for string values, 'boolean' for boolean values. Maps to ``nsITelemetry.SCALAR_TYPE_*``.
+
+``ScalarData``
+~~~~~~~~~~~~~~
+
+Represents registration data for a Telemetry scalar.
+
+Properties:
+
+* ``kind`` - See ScalarType_.
+* ``keyed`` - *(optional, boolean)* True if this is a keyed scalar. Defaults to ``false``.
+* ``record_on_release`` - *(optional, boolean)* True if this data should be recorded on release. Defaults to ``false``.
+* ``expired`` - *(optional, boolean)* True if this scalar entry is expired. Operations on an expired scalar don't error (operations on an undefined scalar do), but the operations are no-ops. No data will be recorded. Defaults to ``false``.
+
+``EventData``
+~~~~~~~~~~~~~
+
+Represents registration data for a Telemetry event.
+
+Properties:
+
+* ``methods`` - *(array)* List of methods for this event entry.
+* ``objects`` - *(array)* List of objects for this event entry.
+* ``extra_keys`` - *(array)* List of allowed extra keys for this event entry.
+* ``record_on_release`` - *(optional, boolean)* True if this data should be recorded on release. Defaults to ``false``.
+* ``expired`` - *(optional, boolean)* True if this event entry is expired. Recording an expired event doesn't error (operations on undefined events do). No data will be recorded. Defaults to ``false``.
+
+Functions
+---------
+
+``submitPing``
+~~~~~~~~~~~~~~
+
+.. code-block:: js
+
+  browser.telemetry.submitPing(type, message, options);
+
+Submits a custom ping to the Telemetry backend. See :ref:`submitting-customping`.
+
+* ``type`` - *(string)* The type of the ping.
+* ``message`` - *(object)* The data payload for the ping.
+* ``options`` - *(optional, object)* Options object.
+
+  * ``addClientId`` - *(optional, boolean)* True if the ping should contain the client id. Defaults to ``false``.
+  * ``addEnvironment`` - *(optional, boolean)* True if the ping should contain the environment data. Defaults to ``false``.
+  * ``overrideEnvironment`` - *(optional, object)* Set to override the environment data. Default: not set.
+  * ``usePingSender`` - *(optional, boolean)* If true, send the ping using the PingSender. Defaults to ``false``.
+
+
+``canUpload``
+~~~~~~~~~~~~~
+
+.. code-block:: js
+
+  browser.telemetry.canUpload();
+
+Checks if Telemetry upload is enabled.
+
+``scalarAdd``
+~~~~~~~~~~~~~
+
+.. code-block:: js
+
+  browser.telemetry.scalarAdd(name, value);
+
+Adds the value to the given scalar.
+
+* ``name`` - *(string)* The scalar name.
+* ``value`` - *(integer)* The numeric value to add to the scalar. Only unsigned integers supported.
+
+``scalarSet``
+~~~~~~~~~~~~~
+
+.. code-block:: js
+
+  browser.telemetry.scalarSet(name, value);
+
+Sets the named scalar to the given value. Throws if the value type doesn't match the scalar type.
+
+* ``name`` - *(string)* The scalar name.
+* ``value`` - *(string|boolean|integer|object)* The value to set the scalar to.
+
+``scalarSetMaximum``
+~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: js
+
+  browser.telemetry.scalarSetMaximum(name, value);
+
+Sets the scalar to the maximum of the current and the passed value
+
+* ``name`` - *(string)* The scalar name.
+* ``value`` - *(integer)* The numeric value to set the scalar to. Only unsigned integers supported.
+
+``recordEvent``
+~~~~~~~~~~~~~~~
+
+.. code-block:: js
+
+  browser.telemetry.recordEvent(category, method, object, value, extra);
+
+Record an event in Telemetry. Throws when trying to record an unknown event.
+
+* ``category`` - *(string)* The category name.
+* ``method`` - *(string)* The method name.
+* ``object`` - *(string)* The object name.
+* ``value`` - *(optional, integer)* An optional string value to record.
+* ``extra`` - *(optional, object)* An optional object of the form (string -> string). It should only contain registered extra keys.
+
+``registerScalars``
+~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: js
+
+  browser.telemetry.registerScalars(category, data);
+
+Register new scalars to record them from addons. See :ref:`registerscalars` for more details.
+
+* ``category`` - *(string)* The unique category the scalars are registered in.
+* ``data`` - *(object)* An object that contains registration data for multiple scalars. Each property name is the scalar name, and the corresponding property value is an object of ScalarData_ type.
+
+``registerEvents``
+~~~~~~~~~~~~~~~~~~
+
+.. code-block:: js
+
+  browser.telemetry.registerEvents(category, data);
+
+Register new events to record them from addons. See :ref:`registerevents` for more details.
+
+* ``category`` - *(string)* The unique category the events are registered in.
+* ``data`` - *(object)* An object that contains registration data for 1+ events. Each property name is the category name, and the corresponding property value is an object of EventData_ type.
+
+``setEventRecordingEnabled``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: js
+
+  browser.telemetry.setEventRecordingEnabled(category, enabled);
+
+Enable recording of events in a category. Events default to recording disabled. This allows to toggle recording for all events in the specified category.
+
+* ``category`` - *(string)* The category name.
+* ``enabled`` - *(boolean)* Whether recording is enabled for events in that category.