Skip to content

Adding Glean Telemetry Events and Metrics

Jump to bottom
Isabella edited this page Aug 22, 2025 · 7 revisions

This guide describes the process and implementation details for adding new and/or updating existing telemetry in the project.

💡 It is important that all new and updated telemetry requirements be reviewed by:

  • a Mozilla Data Steward (to ensure data collection is in line with Mozilla's policies)
  • an iOS Telemetry Steward (to ensure we are following best practices around telemetry naming and other implementation details)

💡 We will soon have a handy telemetry tool which can help you name new probes. For the meantime, you can refer to the Probe Taxonomy Guidelines Proposal document.

Process Overview:

  • (A.) Update the Telemetry Specification YAML Files
  • (B.) Add a New (or Update an Existing) Telemetry Struct in Swift
  • (C.) Use the Glean Debugger to Test Your Code
  • (D.) Write Unit Tests for Your New Telemetry
  • (E.) Pull Request Your Changes
  • (F.) Request a Data Steward Review
  • (G.) Request an iOS Telemetry Steward Review
  • (H.) Request a Regular Code Review
  • (I.) Add QA Test Notes to Your Ticket

(A.) Update the Telemetry Specification YAML Files

📖 tl;dr Add your new telemetry into the appropriate Glean/probes/ YAML file and update the glean_index.yaml and gleanProbes.xcfilelist as needed, or use the FirefoxTelemetryUtility.sh script to help you add a new YAML file.

We are in the process of breaking up our monolithic metrics.yaml file into smaller feature-specific YAML files. These files are located in the Client/Glean/probes subdirectory.

Each of these metric YAML files is processed by the "Glean SDK Generator Script" build phase step in Xcode and compiled into Swift code in the generated file located at /Client/Generated/Metrics/Metrics.swift.

When adding or changing telemetry, you will need to do so in the correct YAML file. If you are working on a new feature or component, you may have to add a new YAML file.

Updating an existing metrics YAML file

If you are adding telemetry for a feature that already has an associated metrics YAML file, add your new telemetry there (skip to Adding a New Probe for details).

For example, telemetry related to the Settings screens in the app should be added to the settings.yaml file.

Adding a new metrics YAML file

If a file does not currently exist for your feature-specific telemetry, you can generate a new file automatically using the utility script FirefoxTelemetryUtility.sh .

To add a new feature YAML, run this command in your terminal from the root directory:

./FirefoxTelemetryUtility.sh --add FeatureName "This is an optional parameter which describes the feature and acts as a tag description."

This will create the following YAML file: Client/Glean/probes/feature_name.yaml .

The script also will automatically append this new file path to the glean_index.yaml file (which the probe-scraper repository uses to update the Glean Dictionary) and the gleanProbes.xcfilelist file (which is an input file list into the "Glean SDK Generator Script" build phase step in Xcode, which will turn your YAML specification into Swift code).

If you have chosen to add the YAML file manually, you can update the file paths in glean_index.yaml and gleanProbes.xcfilelist as described above automatically by running:

./FirefoxTelemetryUtility.sh --update

If you prefer to do everything, manually, here are the steps:

  • Add a new YAML file in the Glean/probes subdirectory
  • Add the new file's path (relative to the root directory) to the metrics_files section of the glean_index.yaml file
  • Add the new file's path (relative to the firefox-ios directory) to gleanProbes.xcfilelist, prefixed by the Xcode environment variable $(PROJECT_DIR)

Adding a New Probe

The following is an example of the general format for adding a new event (user interaction) or metric (user attribute) to a one of our Glean YAML files:

tabs_panel:
  done_button_tapped:
    type: event
    description: |
      Recorded when a user taps the done button to close the tabs panel.
    extra_keys:
      mode:
        type: string
        description: |
          The current tabs panel mode (normal or private or sync).
    bugs:
      - https://github.com/mozilla-mobile/firefox-ios/issues/7526
    data_reviews:
      - https://github.com/mozilla-mobile/firefox-ios/pull/26131
    notification_emails:
      - [email protected]
    expires: "2025-12-01"
    metadata:
      tags:
        - TabsPanel

You can read more about the available options in the Glean documentation on the Metrics YAML Registry Format page. But a few details are also included below.

Glean Metric type

The Glean documentation describes the available metric types. Some of the types we currently use in our codebase are event, boolean, string, counter, labeled_counter, quantity, datetime, timespan, timing_distribution, uuid, object, and url.

In most cases, if you're recording a user interaction you'll want an event, which allows you to record extra_keys to pass additional information. Other types do not support extra_keys, although the object type has the flexibility of passing custom objects.

💡 Note that not all metrics types found in the Glean documentation have been implemented in the Glean SDK for iOS. You can verify that a metric type is available for iOS by checking for Swift code samples under the Recording API section.

Telemetry Expiry Dates

Our telemetry expiry process is currently under review. For now, we can continue with the old process:

💡 For the expiry date, we try to group all metrics within 6 month expiry windows for easy renewal. Check the next expiry window (e.g. 2026-01-01) and align your new metrics with that. If the renewal window is close, you can choose the next one that is in a little over 6 months. Metrics that are being explicitly expired and retired should include extra documentation in the description field stating this fact.

Generating Swift Code from the YAML files

Once you have added your telemetry to the correct YAML files (and ran FirefoxTelemetryUtility.sh as needed for any new YAML files), you can build and run the Client in Xcode.

The Glean SDK Generator Script Client build phase step will run the Glean SDK Generator script and automatically produce Swift code from your YAML specification files.

As long as your project builds successfully, you should now be able to access the new Glean metric types in your code.

(B.) Add a New (or Update an Existing) Telemetry Struct in Swift

📖 tl;dr Use a struct for your telemetry which takes a GleanWrapper on init.

A lot of our old telemetry uses the TelemetryWrapper.swift. Unfortunately, this file is unwieldily and the pattern prone to error. We now want to write individual structs to group and manage the telemetry related to a single component or feature of the app.

A few examples include: ZoomTelemetry.swift, AppIconSelectionTelemetry.swift, TabsPanelTelemetry.swift, ShareTelemetry.swift, and HomepageTelemetry.swift.

You should inject the GleanWrapper into your initializer:

init(gleanWrapper: GleanWrapper = DefaultGleanWrapper()) {
	self.gleanWrapper = gleanWrapper
	...
}

Eventually we hope to completely abstract away the Glean library from our code so an import Glean isn't necessary in each telemetry file.

(C.) Use the Glean Debugger to Test Your Code

Once you are recording telemetry, you should verify your work using the Glean Debugger Dashboard. This is the same tool QA will use to test your telemetry.

For detailed instructions on how to set up testing and how to use the Glean Debugger, visit the Wiki page section on Verifying Glean Ping Data in the Debug Dashboard.

To send telemetry from your simulator to the glean debugger, you can launch the app using the following deep link URL. Replace <YOUR-TAG-HERE> with your own personal testing tag.

xcrun simctl openurl booted "firefox://glean?logPings=true&debugViewTag=<YOUR-TAG-HERE>&sendPing=metrics"

(D.) Write Unit Tests for Your New Telemetry

If you followed the instructions in Step B above to record your feature telemetry in a single telemetry struct, you should have an easier time writing unit tests for your telemetry.

Implementation examples of how to use the MockGleanWrapper type can be found in: ZoomTelemetryTests.swift, AppIconSelectionTelemetryTests.swift, and ShareTelemetryTests.swift.

See the Unit Testing Glean Telemetry wiki page for more details on setting up mocks as needed.

(E.) Pull Request Your Changes

Once you've finished updating the code, you should make a pull request for your telemetry changes.

If you have added new telemetry (or revised existing telemetry), you need to proceed to Step F and request a Data Steward review.

(F.) Request a Data Steward Review

If you add new telemetry, or revise existing telemetry (e.g. add new extras to an existing probe, change the probe type, etc.), you must request a Mozilla Data Steward Review on your pull request.

If in doubt, request a review.

💡 Note: You do not need to request a data steward review for the following cases:

  • renaming probes
  • adding a new tag to existing probes
  • updating probe documentation
  • adding a new label to an existing labelled metric (or a new value to an existing event extra key/value pair)
    • ❗ request a review if the new label or value measures something completely different than previous labels or values

Step 1) Fill out a formal request template

To request a Mozilla Data Steward review, you first must fill out a formal request template and add it to your PR in a comment.

Data Steward Request Form: https://github.com/mozilla/data-review/blob/main/request.md

Step 2) Tag a Mozilla Data Steward for a review

Next, you must tag a Mozilla Data Steward for a review:

  • Roux Buciu (iOS)
  • Roger Yang (Android)
  • If they are not available, you can ask for a review in #data-stewardship-help

Notes & Reference

❗ Any changes to the Adjust implementation must also go through a data review

Example Request: https://github.com/mozilla-mobile/firefox-ios/pull/26555#issuecomment-2855647584

See also: https://wiki.mozilla.org/Firefox/Data_Collection

(G.) Request an iOS Telemetry Steward Review

Not to be confused with the Mozilla Data Stewards, the iOS Telemetry Stewards simply ensure certain best practices are followed so we have consistent telemetry naming, good business purposes behind telemetry, and proper use of the telemetry tools available to us.

You can ask for an iOS telemetry steward review (or help with telemetry naming and other implementation details) in #firefox-ios-dev.

💡 This technical review process is a work in progress. More details will be added to the wiki in 2025 H2. As well, we will soon have a handy telemetry tool which can help you name new probes. For the meantime, you can refer to the Probe Taxonomy Guidelines Proposal document.

(H.) Request a Regular Code Review

You should also tag a member of the iOS team for an actual code review. This happens automatically when you initially create a PR to Firefox for iOS without specifying any reviewers.

The Mozilla Data Steward and the iOS Telemetry Steward only ensure that best practices are followed and generally won't test or review your implementation.

(I.) Add QA Test Notes to Your Ticket

Once your PR is merged, make sure your FXIOS ticket description (or comments) include enough details for QA to effectively test your telemetry.

Examples of what those details might look like:

Technical Details About the probe-scraper

You only need to read this section if you are debugging issues with the probe-scraper.

The probe-scraper scrapes changes in platform metrics (Desktop, Android, and iOS). This data is eventually published as JSON probeinfo (dev, beta, and release) and published in the iOS Glean dictionary.

The probe-scraper repository has a bot script (fog_update.py) which runs on a GitHub action every UTC morning. The script fetches our glean_index.yaml file directly from GitHub (raw.githubusercontent.com) then extracts the relevant metrics, pings, and tags lists. Next, the script rewrites the appropriate section of file references in the probe-scraper's repositories.yaml file, making sure all files from the glean_index.yaml are included. Lastly, a probe-scraper PR is created for any changes which requires a manual review by the Glean team (see an example here).

This system was set up for iOS in June 2025 with Firefox for iOS PR 26910 and probe-scraper PR 909. That is why we can now use the FirefoxTelemetryUtility.sh script to add new metrics files which get picked up by the probe-scraper bot.

There are, however, a few caveats to this system:

  1. The probe-scraper GitHub action will fail if you delete an existing metrics.yaml file in your PR
    1. However, the probe-scraper bot will self-correct things next time it runs; there's no longer a need to make a manual PR as we did in the past
  2. Newly added metrics files in a PR will not be picked up until the next time the probe-scraper bot is triggered after that PR is merged
    1. This may only be a concern if we need to backport and immediately release telemetry for some reason

Since Firefox for iOS gets enough PRs each day, there was no reason to add an additional nightly task on the probe-scraper side to check for new metrics at this time. But it is good to be aware that changes won't take effect until the next PR, whatever it may be, is also merged and runs the iOS probe-scraper action.

Renewing Data

💡 This process is currently under review for 2025. The following may be old information:

Every 6 months, the product team will review all telemetry and answer:

Clone this wiki locally