Telemetry Events Best Practices
The Telemetry Events API allows users to define and record events in the browser.
Events are defined in
Events.yaml and each events creates records with the following properties:
With the following restrictions and features:
- The category, method, and object properties of any record produced by an event must have a value.
- All combinations of values from the category, method, and object properties must be unique to that particular event (no other event can produce events with the same combination).
- Events can be 'turned on' or 'turned off' by it's category value. i.e. we can instruct the browser to "stop sending us events from the
One challenge with this data is it can be difficult to identify all the records from a particular event. Unlike Scalars and Histograms, which keep data in individual locations (like
total_uri_count), all event records are stored together, regardless of which event generated them. The records themselves don't have a field identifying which event produced it.
Take, for example, the
event in the
addonsManager: # category manage: # event name description: > ... objects: ["extension", "theme", "locale", "dictionary", "other"] # object values methods: ["disable", "enable", "sideload_prompt", "uninstall"] # method values extra_keys: # extra values ... notification_emails: ... expiry_version: ... record_in_processes: ... bug_numbers: ... release_channel_collection: ...
This event will produce records that look like:
But none of these records will indicate that it was produced by the
manage event. To find all records produced by
manage, one would have to query all records where
category = ... AND method in [...,] AND object in [...,]
which is not ideal.
Furthermore, if one encounters this data without knowledge of how the
manage event works, they need to look up the event based on the category, method, and object values in order to find the event, and then query the data again to find all the related events. It's not immediately clear from the data if this record:
and and this record:
are related or not.
Another factor that can add to confusion is the fact that other events can share similar values for methods or objects (or even the combination of method and object). For example:
which can further confuser users.
: Events do have name fields, but they aren't included in the event records and thus are not present in the resulting dataset. Also, If a user defines an event in
Events.yaml without specifying a list of acceptable methods, the method will default to the name of the event for records created by that event.
To simplify things in the future, we suggest adding the event name to the category field using dot notation when designing new events:
This provides 3 advantages:
- Records produced by this event will be easily identifiable. Also, the event which produced the record will be easier to locate in the code.
- Events can be controlled more easily. The category field is what we use to "turn on" and "turn off" events. By creating a 1 to 1 mapping between categories and events, we can control events on an individual level.
- By having the category field act as the event identifier, it makes it easier to pass on events to Amplitude and other platforms.