“event” ping

This ping transmits Telemetry Event records.

The client id is submitted with this ping. The Telemetry Environment is submitted in this ping.

{
  "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 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 session split 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 Event Summary.

events

A map from process names to arrays of event records that have been serialized.

Version History

• Firefox 62: Started sending the “event” ping (bug 1460595).