1 files changed, 92 insertions, 0 deletions
diff --git a/toolkit/components/telemetry/docs/data/event-ping.rst b/toolkit/components/telemetry/docs/data/event-ping.rst
new file mode 100644
index 0000000000..05fdd60a0f
--- /dev/null
+++ b/toolkit/components/telemetry/docs/data/event-ping.rst
@@ -0,0 +1,92 @@
+
+"event" ping
+=============
+
+This ping transmits :ref:`Telemetry Event <eventtelemetry>` records.
+
+The client id is submitted with this ping.
+The :doc:`Telemetry Environment <../data/environment>` is submitted in this ping.
+
+.. code-block:: js
+
+    {
+      "type": "event",
+      ... common ping data
+      "clientId": <UUID>,
+      "environment": { ... },
+      "payload": {
+        "reason": {periodic, max, shutdown}, // Why the ping was submitted
+        "processStartTimestamp": <UNIX Timestamp>, // Minute precision, for calculating absolute time across pings
+        "sessionId": <UUID>, // For linking to "main" pings
+        "subsessionId": <UUID>, // For linking to "main" pings
+        "lostEventsCount": <number>, // How many events we had to drop. Valid only for reasons "max" and "shutdown"
+        "events": {
+          "parent": [ // process name, one of the keys from Processes.yaml
+            [timestamp, category, method, object, value, extra],
+            ... // At most 1000
+          ]
+        }
+      }
+    }
+
+Send behavior
+-------------
+
+The ping is submitted at most once per ten minute interval, and at least once per hour in
+which an event was recorded. Upon reaching 1000 events, the ping is sent immediately
+unless it would be within ten minutes of the previous ping, in which case some event
+records may be lost. A count of these lost records is included in the ping.
+to avoid losing collected data.
+
+On shutdown, during profile-before-change, a final ping is sent with any remaining event
+records, regardless of frequency but obeying the event record limit.
+
+The 1000-record limit and one-hour and ten-minute frequencies are controlled by
+:doc:`preferences <../internals/preferences>`.
+
+Field details
+-------------
+
+reason
+~~~~~~
+The ``reason`` field contains the information about why the "event" ping was submitted:
+
+* ``periodic``: The event ping was submitted because at least one event happened in the past hour.
+* ``max``: The event ping was submitted because the 1000-record limit was reached.
+* ``shutdown``: The event ping was submitted because Firefox is shutting down and some events
+  have yet to be submitted.
+
+processStartTimestamp
+~~~~~~~~~~~~~~~~~~~~~
+The minute the user's Firefox main process was created. Event record timestamps are recorded
+relative to Firefox's main process start. This provides the basis for reconstructing a user's full
+session of events in order, as well as offering a mechanism for grouping event pings.
+
+sessionId
+~~~~~~~~~
+The id of the session that was current when the ping was sent.
+
+subsessionId
+~~~~~~~~~~~~
+The id of the subsession that was current when the ping was sent.
+
+.. note::
+
+  This may not be the same subsession that the events occurred in if a
+  :ref:`session split <sessionsplit>` happened in between.
+
+lostEventsCount
+~~~~~~~~~~~~~~~
+The number of events we had to discard because we reached the 1000-per-ping limit before
+we were able to send the ping. Should only have a non-zero value on "event" pings with
+reason set to "max" or "shutdown". Which events are missing should be calculable via the
+client's "main" pings using :ref:`Event Summary <events.event-summary>`.
+
+events
+~~~~~~
+A map from process names to arrays of event records that have been :ref:`serialized <events.serializationformat>`.
+
+Version History
+---------------
+
+- Firefox 62: Started sending the "event" ping (`bug 1460595 <https://bugzilla.mozilla.org/show_bug.cgi?id=1460595>`_).