New Metrics and Pings¶
To add a new metric or ping to Firefox Desktop you should follow the Glean SDK documentation on the subject, with some few twists we detail herein:
Instrumentation, being code, should be tested. Firefox on Glean supports a wide variety of Firefox Desktop test suites in addition to Glean’s own debugging mechanisms.
Firefox Desktop is made of multiple processes. You can record data from any process in Firefox Desktop subject to certain conditions.
If you will be recording data to this metric in multiple processes, you should make yourself aware of those conditions.
Where do I Define new Metrics and Pings?¶
Metrics and pings are defined in their definitions files
But where can you find
If you’re not the first person in your component to ask that question,
the answer is likely “in the root of your component”.
Look for the definitions files near to where you are instrumenting your code.
Or you can look in
to see the list of all currently-known definitions files.
If you are the first person in your component to ask that question,
you get to choose where to start them!
We recommend adding them in the root of your component, next to a
Be sure to link to this document at the top of the file!
It contains many useful tidbits of information that anyone adding new metrics should know.
Preferably, use this blank template to get started,
substituting your component’s
product :: component tag from
# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
# Adding a new metric? We have docs for that!
- 'Your Product :: Your Component'
If you add a new definitions file, be sure to edit
adding your definitions files to the Python lists therein.
If you don’t, no API will be generated for your metrics and your build will fail.
You will have to decide which products your metrics will be used in.
For code that’s also used in other Gecko-based products (Firefox Desktop, Firefox for Android, Focus for Android), use
For Desktop-only instrumentation use
For other products use their respective lists.
metrics_index.py are automatically reflected in the data pipeline once a day
using the fog-updater automation in probe-scraper.
Data will not show up in datasets and tools until this happens.
If something is unclear or data is not showing up in time you will need to file a bug in
Data Platform and Tools :: General.
If you have any questions, be sure to ask on the #glean channel.
Note: Do not use
These are for metrics instrumenting the code under
and are not general-purpose locations for adding metrics and pings.
How does Expiry Work?¶
In FOG, unlike in other Glean-SDK-using projects, metrics expire based on Firefox application version. This is to allow metrics to be valid over the entire life of an application version, whether that is the 4-6 weeks of usual releases or the 13 months of ESR releases.
There are three values accepted in the
expires field of
metrics.yamls for FOG:
Xis the major portion of a Firefox Desktop version) - The metric will be expired when the
MOZ_APP_VERSIONreaches or exceeds
X. (For example, when the Firefox Version is
88.0a1, all metrics marked with
expires: "88"or lower will be expired.) This is the recommended form for all new metrics to ensure they stop recording when they stop being relevant.
expired- For marking a metric as manually expired. Not usually used, but sometimes helpful for internal tests.
never- For marking a metric as part of a permanent data collection. Metrics marked with
nevermust have instrumentation tests.
For more information on what expiry means and the
metrics.yaml format, see
the Glean SDK docs
on this subject. Some quick facts:
Data collected to expired metrics is not recorded or sent.
Recording to expired metrics is not an error at runtime.
Expired metrics being in a
metrics.yamlis a linting error in
Expired (and non-expired) metrics that are no longer useful should be promptly removed from your
metrics.yaml. This reduces the size and improves the performance of Firefox (and speeds up the Firefox build process) by decreasing the amount of code that needs to be generated.