93 lines
3.4 KiB
ReStructuredText
93 lines
3.4 KiB
ReStructuredText
|
|
"event" ping
|
|
=============
|
|
|
|
This ping transmits :ref:`Telemetry Event <eventtelemetry>` records.
|
|
|
|
The client id and profile group id are 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>,
|
|
"profileGroupId": <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>`_).
|