Bug 1318297 - Add docs. r=liuche
authorKate Ustiuzhanina <kustiuzhanina@mozilla.com>
Mon, 24 Jul 2017 13:10:25 +0100
changeset 420035 03d1cedf6f127bac8b3f6e7f4f89930bf97bea0c
parent 420034 d260dd770741e0b3899ed929f432dabaf10cba24
child 420036 58dd26b26962b48ab5e1b79a05e35c864ccd52a8
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)
reviewersliuche
bugs1318297
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 1318297 - Add docs. r=liuche
toolkit/components/telemetry/docs/data/health-ping.rst
new file mode 100644
--- /dev/null
+++ b/toolkit/components/telemetry/docs/data/health-ping.rst
@@ -0,0 +1,80 @@
+
+"health" ping
+============
+
+This ping is intended to provide data about problems arise when submitting other pings.
+The ping is submitted at most once per hour. On shutdown an additional ping is submitted
+to avoid losing collected data.
+
+This ping is intended to be really small.
+The client id is submitted with this ping.
+
+.. code-block:: js
+
+    {
+      "type": "health", // type
+      ... common ping data
+      "clientId": <UUID>, // client id, e.g.
+                            // "c641eacf-c30c-4171-b403-f077724e848a"
+      "payload": {
+        "os": {
+            "name": <string>, // OS name
+            "version": <string> // OS version
+        },
+        "reason": <string>, // When ping was triggered, e.g. "immediate" or "shutdown".
+        "pingDiscardedForSize": {
+            "main": <number>, // Amount of occurrences for a specific ping type.
+            "core": <number>
+            ...
+        },
+        "sendFailure": {
+            "timeout": <number>, // Amount of occurrences for a specific failure.
+            "abort": <number>
+            ...
+        }
+      }
+    }
+
+Send behavior
+-------------
+
+``TelemetryHealthPing.jsm`` tracks several problems:
+
+* The size of other assembled ping exceed the ping limit.
+* There was a failure while sending other ping.
+
+After recording the data, ping will be sent:
+
+* immediately, with the reason ``immediate`` , if it is first ping in the session or it passed at least one hour from the previous submission.
+* after 1 hour minus the time passed from previous submission, with the reason ``delayed`` , if less than an hour passed from the previous submission.
+* on shutdown, with the reason ``shutdown`` , if recorded data is not empty.
+
+Field details
+-------------
+
+reason
+~~~~~~
+The ``reason`` field contains the information about when "health" ping was submitted. Now it supports three types:
+
+* immediate: The health ping was submitted immediately after recording a failure.
+* delayed: The health ping was submitted after a delay.
+* shutdown: The health ping was submitted on shutdown.
+
+pingDiscardedForSize
+~~~~~~~~~~~~~~~~~~~~
+The ``pingDiscardedForSize`` field contains the information about top ten pings, whose size exceeded the
+ping size limit (1 mb). This field lists the number of discarded pings per ping type.
+
+This field is optional.
+
+sendFailure
+~~~~~~~~~~~
+The ``sendFailure`` field contains the information about pings, which had failures on sending.
+This field lists the number of failed pings per ping send failure type.
+
+This field is optional.
+
+.. note::
+
+    Although both ``pingDiscardedForSize`` and ``sendFailure`` fields are optional, the health ping will only
+    be submitted if one of this field not empty.