author ffxbld <>
Mon, 17 Jun 2019 12:49:45 +0000
changeset 533938 080ef15620cf31461faf8ad853561c49c3dfe373
parent 518002 e141df747cab157c4c54fc6174125b1503e7480e
permissions -rw-r--r--
No Bug, mozilla-beta repo-update HSTS HPKP blocklist remote-settings - r=jcristau, a=repo-update Differential Revision:

"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

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.

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.

The id of the session that was current when the ping was sent.

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.

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>`.

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 <>`_).