Bug 1301313 - Add submission constraints to Telemetry custom ping documentation. r=dexter
authorGeorg Fritzsche <georg.fritzsche@googlemail.com>
Fri, 09 Sep 2016 00:43:25 +0700
changeset 354586 48d6981fbef25b2c0ff0e66a3d3be2aa8c81fb1b
parent 354585 ef963f64fe0ee37d3ad19ccef88b8b4fe549e694
child 354587 23db1f3f19e926b2493fa8d36aa2df1b7455a85b
push id6570
push userraliiev@mozilla.com
push dateMon, 14 Nov 2016 12:26:13 +0000
treeherdermozilla-beta@f455459b2ae5 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersdexter
bugs1301313
milestone51.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 1301313 - Add submission constraints to Telemetry custom ping documentation. r=dexter
toolkit/components/telemetry/docs/collection/custom-pings.rst
--- a/toolkit/components/telemetry/docs/collection/custom-pings.rst
+++ b/toolkit/components/telemetry/docs/collection/custom-pings.rst
@@ -4,26 +4,41 @@ Submitting custom pings
 
 Custom pings can be submitted from JavaScript using:
 
 .. code-block:: js
 
     TelemetryController.submitExternalPing(type, payload, options)
 
 - ``type`` - a ``string`` that is the type of the ping, limited to ``/^[a-z0-9][a-z0-9-]+[a-z0-9]$/i``.
-- ``payload`` - the actual payload data for the ping, should be a JSON style object.
+- ``payload`` - the actual payload data for the ping, has to be a JSON style object.
 - ``options`` - optional, an object containing additional options:
    - ``addClientId``- whether to add the client id to the ping, defaults to ``false``
    - ``addEnvironment`` - whether to add the environment data to the ping, defaults to ``false``
    - ``overrideEnvironment`` - a JSON style object that overrides the environment data
 
 ``TelemetryController`` will assemble a ping with the passed payload and the specified options.
 That ping will be archived locally for use with Shield and inspection in ``about:telemetry``.
 If the preferences allow upload of Telemetry pings, the ping will be uploaded at the next opportunity (this is subject to throttling, retry-on-failure, etc.).
 
+Submission constraints
+----------------------
+
+When submitting pings on shutdown, they should not be submitted after Telemetry shutdown.
+Pings should be submitted at the latest within:
+
+- the `observer notification <https://developer.mozilla.org/de/docs/Observer_Notifications#Application_shutdown>`_ ``"profile-before-change"``
+- the :ref:`AsyncShutdown phase <AsyncShutdown_phases>` ``sendTelemetry``
+
+There are other constraints that can lead to a ping submission getting dropped:
+
+- invalid ping type strings
+- invalid payload types: E.g. strings instead of objects.
+- oversized payloads: We currently only drop pings >1MB, but targetting sizes of <=10KB is recommended.
+
 Tools
 =====
 
 Helpful tools for designing new pings include:
 
 - `gzipServer <https://github.com/mozilla/gzipServer>`_ - a Python script that can run locally and receives and saves Telemetry pings. Making Firefox send to it allows inspecting outgoing pings easily.
 - ``about:telemetry`` - allows inspecting submitted pings from the local archive, including all custom ones.