Migrating Firefox Telemetry to Glean

This guide aims to help you migrate individual data collections from Firefox Telemetry to Glean via Firefox on Glean.

This is intended to be a reference to help you fill out your migration worksheet, or for mentally translating Telemetry concepts to Glean ones.

General Things To Bear In Mind

You should familiarize yourself with the guide on adding new metrics to Firefox Desktop. Its advice stacks with the advice included in this guide as (once you’ve figured out what kind) you will indeed be adding new metrics.

There are some other broad topics specific to migrating Firefox Telemetry stuff to Glean stuff:

Process-Agnosticism: No more record_in_processes field

Glean (and thus FOG) doesn’t know anything about processes except what it has to in order to ensure all the data makes it to the parent process. Firefox Telemetry cared very much about which process was collecting which specific data, keeping them separate.

If you collect data in multiple processes and wish to keep data from each process type separate, you will need to provide this separation yourself.

Please see this dev doc for an example of how to do that.

Channel-Agnosticism: No more release_channel_collection: opt-out

FOG doesn’t make a differentiation between pre-release Firefox and release Firefox, except inasmuch as is necessary to put the correct channel in client_info.app_channel.

This means all data is collected in all build configurations.

If you wish or are required to only collect your data in pre-release Firefox, please avail yourself of the EARLY_BETA_OR_EARLIER #define or AppConstant.

File-level Product Inclusion/Exclusion: No more products field

Glean determines which metrics are recorded in which products via a dependency tree. This means FOG doesn’t distinguish between products at the per-product level.

If some of your metrics are recorded in different sets of products (e.g. some of your metrics are collected in both Firefox Desktop and Firefox for Android, but others are Firefox Desktop-specific) you must separate them into separate definitions files.

Many Definitions Files

Each component is expected to own and care for its own metrics definitions files. There is no centralized Histograms.json or Scalars.yaml or Events.yaml.

Instead the component being instrumented will have its own metrics.yaml (and pings.yaml for any [Custom Pings][custom-pings]) in which you will define the data.

See this guide for details.

Testing

Firefox Telemetry had very uneven support for testing instrumentation code. FOG has much better support. Anywhere you can instrument is someplace you can test.

It’s as simple as calling testGetValue.

All migrated collections are expected to be tested. If you can’t test them, then you’d better have an exceptionally good reason why not.

For more details, please peruse the instrumentation testing docs.

Which Glean Metric Type Should I Use?

Glean uses higher-level metric types than Firefox Telemetry does. This complicates migration as something that is “just a number” in Firefox Telemetry might map to any number of Glean metric types.

Please choose the most specific metric type that solves your problem. This’ll make analysis easier as

  1. Others will know more about how to analyse the metric from more specific types.

  2. Tooling will be able to present only relevant operations for more specific types.

Example:

In Firefox Telemetry I record the number of monitors attached to the computer that Firefox Desktop is running on. I could record this number as a string, a counter, or a quantity. The string is an obvious trap. It doesn’t even have the correct data type (string vs number). But is it a counter or quantity? If you pay attention to this guide you’ll learn that counters are used to accumulate sums of information, whereas quantity metrics are used to record specific values. The “sum” of monitors over time doesn’t make sense, so counter is out. quantity is the correct choice.

Histograms

Histograms are the oldest Firefox Telemetry data type, and as such they’ve accumulated (ha!) the most ways of being used.

Scalar Values in Histograms: kind flag and count

If you have a Histogram that records exactly one value, please scroll down and look at the migration guide for the relevant Scalar:

  • For Histograms of kind flag see “Scalars of kind bool

  • For Histograms of kind count see “Scalars of kind uint

Continuous Distributions: kind linear and exponential

If the Histogram you wish to migrate is formed of multiple buckets that together form a single continuous range (like you have buckets 1-5, 6-10, 11-19, and 20-50 - they form the range 1-50), then you will want a “distribution” metric type in Glean. Which kind of “distribution” metric type depends on what the samples are.

Timing samples - Use Glean’s timing_distribution

The most common type of continuous distribution in Firefox Telemetry is a histogram of timing samples like GC_MS.

In Glean this sort of data is recorded using a timing-distribution metric type.

You will no longer need to worry about the range of values or number or distribution of buckets (represented by the low, high, n_buckets, or kind in your Histogram’s definition). Glean uses a clever automatic bucketing algorithm instead.

So for a Histogram that records timing samples like this:

  "GC_MS": {
    "record_in_processes": ["main", "content"],
    "products": ["firefox"],
    "alert_emails": ["dev-telemetry-gc-alerts@mozilla.org", "jcoppeard@mozilla.com"],
    "expires_in_version": "never",
    "releaseChannelCollection": "opt-out",
    "kind": "exponential",
    "high": 10000,
    "n_buckets": 50,
    "bug_numbers": [1636419],
    "description": "Time spent running JS GC (ms)"
  },

You will migrate to a timing_distibution metric type like this:

js:
  gc:
    type: timing_distribution
    time_unit: millisecond
    description: |
      Time spent running the Javascript Garbage Collector.
      Migrated from Firefox Telemetry's `GC_MS`.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1636419
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1636419#c8
    data_sensitivity:
      - technical
    notification_emails:
      - dev-telemetry-gc-alerts@mozilla.org
      - jcoppeard@mozilla.com
    expires: never

GIFFT: This type of collection is mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions.

Memory Samples - Use Glean’s memory_distribution

Another common content of linear or exponential Histograms in Firefox Telemetry is memory samples. For example, MEMORY_TOTAL’s samples are in kilobytes.

In Glean this sort of data is recorded using a memory-distribution metric type.

You will no longer need to worry about the range of values or number or distribution of buckets (represented by the low, high, n_buckets, or kind in your Histogram’s definition). Glean uses a clever automatic bucketing algorithm instead.

So for a Histogram that records memory samples like this:

  "MEMORY_TOTAL": {
    "record_in_processes": ["main"],
    "products": ["firefox", "thunderbird"],
    "alert_emails": ["memshrink-telemetry-alerts@mozilla.com", "amccreight@mozilla.com"],
    "bug_numbers": [1198209, 1511918],
    "expires_in_version": "never",
    "kind": "exponential",
    "low": 32768,
    "high": 16777216,
    "n_buckets": 100,
    "description": "Total Memory Across All Processes (KB)",
    "releaseChannelCollection": "opt-out"
  },

You will migrate to a memory_distribution metric type like this:

memory:
  total:
    type: memory_distribution
    memory_unit: kilobyte
    description: |
      The total memory allocated across all processes.
      Migrated from Telemetry's `MEMORY_TOTAL`.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1198209
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1511918
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1511918#c9
    data_sensitivity:
      - technical
    notification_emails:
      - memshrink-telemetry-alerts@mozilla.com
      - amccreight@mozilla.com
    expires: never

GIFFT: This type of collection is mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions.

Percentage Samples - Comment on bug 1657467

A very common Histogram in Firefox Desktop is a distribution of percentage samples. For example, GC_SLICE_DURING_IDLE.

Glean doesn’t currently have a good metric type for this. But we intend to add one. If you are migrating a collection of this type, please add a comment to the bug detailing which probe you are migrating, and when you need it migrated by. We’ll prioritize adding this metric type accordingly.

Other - Use Glean’s custom_distribution

Continuous Distribution Histograms have been around long enough to have gotten weird. If you’re migrating one of those histograms with units like “square root of pixels times milliseconds”, we have a “catch all” metric type for you: Custom Distribution.

Sadly, you’ll have to care about the bucketing algorithm and bucket ranges for this one. So for a Histogram with artisinal samples like:

  "CHECKERBOARD_SEVERITY": {
    "record_in_processes": ["main", "content", "gpu"],
    "products": ["firefox"],
    "alert_emails": ["gfx-telemetry-alerts@mozilla.com", "botond@mozilla.com"],
    "bug_numbers": [1238040, 1539309, 1584109],
    "releaseChannelCollection": "opt-out",
    "expires_in_version": "never",
    "kind": "exponential",
    "high": 1073741824,
    "n_buckets": 50,
    "description": "Opaque measure of the severity of a checkerboard event"
  },

You will migrate it to a custom_distribution like:

gfx.checkerboard:
  severity:
    type: custom_distribution
    range_max: 1073741824
    bucket_count: 50
    histogram_type: exponential
    unit: Opaque unit
    description: >
      An opaque measurement of the severity of a checkerboard event.
      This doesn't have units, it's just useful for comparing two checkerboard
      events to see which one is worse, for some implementation-specific
      definition of "worse". The larger the value, the worse the
      checkerboarding.
      Migrated from Telemetry's `CHECKERBOARD_SEVERITY`.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1238040
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1539309
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1584109
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1584109#c1
    notification_emails:
      - gfx-telemetry-alerts@mozilla.com
      - botond@mozilla.com
    data_sensitivity:
      - technical
    expires: never

TODO Bug 1677447: Custom Distributions aren’t yet implemented in FOG. We’re working on it. When they’re done we’ll see if they’ll support GIFFT like the other distributions.

Keyed Histograms with Continuous Sample Distributions - Ask on #glean:mozilla.org for assistance

Glean doesn’t currently have a good metric type for keyed continuous distributions like video play time keyed by codec. Please reach out to us to explain your use-case. We will help you either work within what Glean currently affords or design a new metric type for you.

Discrete Distributions: kind categorical, enumerated, or boolean - Use Glean’s labeled_counter

If the samples don’t fall in a continuous range and instead fall into a known number of buckets, Glean provides the Labeled Counter for these cases.

Simply enumerate the discrete categories as labels in the labeled_counter.

For example, for a Histogram of kind categorical like:

  "AVIF_DECODE_RESULT": {
    "record_in_processes": ["main", "content"],
    "products": ["firefox"],
    "alert_emails": ["cchang@mozilla.com", "jbauman@mozilla.com"],
    "expires_in_version": "never",
    "releaseChannelCollection": "opt-out",
    "kind": "categorical",
    "labels": [
      "success",
      "parse_error",
      "no_primary_item",
      "decode_error",
      "size_overflow",
      "out_of_memory",
      "pipe_init_error",
      "write_buffer_error",
      "alpha_y_sz_mismatch",
      "alpha_y_bpc_mismatch"
    ],
    "description": "Decode result of AVIF image",
    "bug_numbers": [1670827]
  },

You would migrate to a labeled_counter like:

avif:
  decode_result:
    type: labeled_counter,
    description: |
      Each AVIF image's decode result.
      Migrated from Telemetry's `AVIF_DECODE_RESULT`.
    labels:
      - success
      - parse_error
      - no_primary_item
      - decode_error
      - size_overflow
      - out_of_memory
      - pipe_init_error
      - write_buffer_error
      - alpha_y_sz_mismatch
      - alpha_y_bpc_mismatch
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1670827
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1670827#c9
    data_sensitivity:
      - technical
    notification_emails:
      - cchang@mozilla.com
      - jbauman@mozilla.com
    expires: never

GIFFT: This type of collection is mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions. N.B.: This will mirror back as a Keyed Scalar of kind uint, not as any kind of Histogram, so your original un-migrated histogram cannot be used as the mirror.

Keyed Histograms with Discrete Sample Distributions: "keyed": true and kind categorical, enumerated, or boolean - Comment on bug 1657470

Glean doesn’t currently have a good metric type for this. But we intend to add one. If you are migrating a collection of this type, please add a comment to the bug detailing which probe you are migrating, and when you need it migrated by. We’ll prioritize adding this metric type accordingly.

Scalars

Scalars are low-level individual data collections with a variety of uses.

Scalars of kind: uint that you call scalarAdd on - Use Glean’s counter

The most common kind of Scalar is of kind: uint. The most common use of such a scalar is to repeatedly call scalarAdd on it as countable things happen.

The Glean metric type for countable things is the counter metric type.

So for a Scalar like this:

script.preloader:
  mainthread_recompile:
    bug_numbers:
      - 1364235
    description:
      How many times we ended up recompiling a script from the script preloader
      on the main thread.
    expires: "100"
    keyed: false
    kind: uint
    notification_emails:
      - dothayer@mozilla.com
      - plawless@mozilla.com
    release_channel_collection: opt-out
    products:
      - 'firefox'
      - 'fennec'
    record_in_processes:
      - 'main'
      - 'content'

You will migrate to a counter metric type like this:

script.preloader:
  mainthread_recompile:
    type: counter
    description: |
      How many times we ended up recompiling a script from the script preloader
      on the main thread.
      Migrated from Telemetry's `script.preloader.mainthread_recompile`.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1364235
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1364235#c25
    data_sensitivity:
      - technical
    notification_emails:
      - dothayer@mozilla.com
      - plawless@mozilla.com
    expires: "100"

GIFFT: This type of collection is mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions.

Keyed Scalars of kind: uint that you call scalarAdd on - Use Glean’s labeled_counter

Another very common use of Scalars is to have a Keyed Scalar of kind: uint. This was often used to track UI usage.

This is supported by the Glean labeled_counter metric type.

So for a Keyed Scalar of kind: uint like this:

urlbar:
  tips:
    bug_numbers:
      - 1608461
    description: >
      A keyed uint recording how many times particular tips are shown in the
      Urlbar and how often their confirm and help buttons are pressed.
    expires: never
    kind: uint
    keyed: true
    notification_emails:
      - email@example.com
    release_channel_collection: opt-out
    products:
      - 'firefox'
    record_in_processes:
      - main

You would migrate it to a labeled_counter like this:

urlbar:
  tips:
    type: labeled_counter
    description: >
      A keyed uint recording how many times particular tips are shown in the
      Urlbar and how often their confirm and help buttons are pressed.
      Migrated from Telemetry's `urlbar.tips`.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1608461
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1608461#c42
    data_sensitivity:
      - interaction
    expires: never
    notification_emails:
      - email@example.com

Now, if your Keyed Scalar has a list of known keys, you should provide it to the labeled_counter using the labels property like so:

urlbar:
  tips:
    type: labeled_counter
    labels:
      - tabtosearch_onboard_shown
      - tabtosearch_shown
      - searchtip_onboard_shown
    ...

GIFFT: This type of collection is mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions.

Scalars of kind: uint that you call scalarSet on - Use Glean’s quantity

Distinct from counts which are partial sums, Scalars of kind: uint that you set could contain just about anything. The best metric type depends on the type of data you’re setting (See “Other Scalar-ish types” for some possibilities).

If it’s a numerical value you are setting, chances are you will be best served by Glean’s quantity metric type.

For a such a quantitative Scalar like:

gfx.display:
  primary_height:
    bug_numbers:
      - 1594145
    description: >
      Height of the primary display, takes device rotation into account.
    expires: never
    kind: uint
    notification_emails:
      - gfx-telemetry-alerts@mozilla.com
      - ktaeleman@mozilla.com
    products:
      - 'firefox'
    record_in_processes:
      - 'main'
    release_channel_collection: opt-out

You would migrate it to a quantity like:

gfx.display:
  primary_height:
    type: quantity
    unit: pixels
    description: >
      Height of the primary display, takes device rotation into account.
      Migrated from Telemetry's `gfx.display.primary_height`.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1594145
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1687219
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1594145#c4
    data_sensitivity:
      - technical
    notification_emails:
      - gfx-telemetry-alerts@mozilla.com
    expires: never

Note the required unit property.

GIFFT: This type of collection is mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions.

IPC Note: Due to set not being a commutative operation, using quantity on non-parent processes is forbidden. This is a restriction that favours correctness over friendliness, which we may revisit if enough use cases require it. Please contact us if you’d like us to do so.

Keyed Scalars of kind: uint that you call scalarSet on - Ask on #glean:mozilla.org for assistance

Glean doesn’t currently have a good metric type for keyed quantities. Please reach out to us to explain your use-case. We will help you either work within what Glean currently affords or design a new metric type for you.

Scalars of kind: uint that you call scalarSetMaximum or some combination of operations on - Ask on #glean:mozilla.org for assistance

Glean doesn’t currently have a good metric type for dealing with maximums, or for dealing with values you both count and set. Please reach out to us to explain your use-case. We will help you either work within what Glean currently affords or design a new metric type for you.

Scalars of kind: string - Use Glean’s string

If your string value is a unique identifier, then consider Glean’s uuid metric type first.

If the string scalar value doesn’t fit that or any other more specific metric type, then Glean’s string metric type will do.

For a Scalar of kind: string like:

widget:
  gtk_version:
    bug_numbers:
      - 1670145
    description: >
      The version of Gtk 3 in use.
    kind: string
    expires: never
    notification_emails:
      - layout-telemetry-alerts@mozilla.com
    release_channel_collection: opt-out
    products:
      - 'firefox'
    record_in_processes:
      - 'main'

You will migrate it to a string metric like:

widget:
  gtk_version:
    type: string
    description: >
      The version of Gtk 3 in use.
      Migrated from Telemetry's `widget.gtk_version`.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1670145
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1670145#c7
    data_sensitivity:
      - technical
    notification_emails:
      - layout-telemetry-alerts@mozilla.com
    expires: never

GIFFT: This type of collection is mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions.

IPC Note: Due to set not being a commutative operation, using string on non-parent processes is forbidden. This is a restriction that favours correctness over friendliness, which we may revisit if enough use cases require it. Please contact us if you’d like us to do so.

Scalars of kind: boolean - Use Glean’s boolean

If you need to store a simple true/false, Glean’s boolean metric type is likely best.

If you have more that just true and false to store, you may prefer a labeled_counter.

For a Scalar of kind: boolean like:

widget:
  dark_mode:
    bug_numbers:
      - 1601846
    description: >
      Whether the OS theme is dark.
    expires: never
    kind: boolean
    notification_emails:
      - layout-telemetry-alerts@mozilla.com
      - cmccormack@mozilla.com
    release_channel_collection: opt-out
    products:
      - 'firefox'
      - 'fennec'
    record_in_processes:
      - 'main'

You would migrate to a boolean metric type like:

widget:
  dark_mode:
    type: boolean
    description: >
      Whether the OS theme is dark.
      Migrated from Telemetry's `widget.dark_mode`.
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1601846
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1601846#c5
    data_sensitivity:
      - technical
    notification_emails:
      - layout-telemetry-alerts@mozilla.com
      - cmccormack@mozilla.com
    expires: never

GIFFT: This type of collection is mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions.

IPC Note: Due to set not being a commutative operation, using boolean on non-parent processes is forbidden. This is a restriction that favours correctness over friendliness, which we may revisit if enough use cases require it. Please contact us if you’d like us to do so.

Keyed Scalars of kind: boolean - Use Glean’s labeled_boolean

If you have multiple related true/false values, you may have put them in a Keyed Scalar of kind: boolean.

The best match for this is Glean’s labeled_boolean metric type.

For a Keyed Scalar of kind: boolean like:

devtools.tool:
  registered:
    bug_numbers:
      - 1447302
      - 1503568
      - 1587985
    description: >
      Recorded on enable tool checkbox check/uncheck in Developer Tools options
      panel. Boolean stating if the tool was enabled or disabled by the user.
      Keyed by tool id. Current default tools with their id's are defined in
      https://searchfox.org/mozilla-central/source/devtools/client/definitions.js
    expires: never
    kind: boolean
    keyed: true
    notification_emails:
      - dev-developer-tools@lists.mozilla.org
      - accessibility@mozilla.com
    release_channel_collection: opt-out
    products:
      - 'firefox'
      - 'fennec'
    record_in_processes:
      - 'main'

You would migrate to a labeled_boolean like:

devtools.tool:
  registered:
    type: labeled_boolean
    description: >
      Recorded on enable tool checkbox check/uncheck in Developer Tools options
      panel. Boolean stating if the tool was enabled or disabled by the user.
      Migrated from Telemetry's `devtools.tool`.
    labels:
      - options
      - inspector
      - webconsole
      - jsdebugger
      - styleeditor
      - performance
      - memory
      - netmonitor
      - storage
      - dom
      - accessibility
      - application
      - dark
      - light
    bugs:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1447302
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1503568
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1587985
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1447302#c17
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1503568#c3
      - https://bugzilla.mozilla.org/show_bug.cgi?id=1587985#c5
    data_sensitivity:
      - interaction
    notification_emails:
      - dev-developer-tools@lists.mozilla.org
      - accessibility@mozilla.com
    expires: never

GIFFT: This type of collection is mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions.

IPC Note: Due to set not being a commutative operation, using labeled_boolean on non-parent processes is forbidden. This is a restriction that favours correctness over friendliness, which we may revisit if enough use cases require it. Please contact us if you’d like us to do so.

Other Scalar-ish types: rate, timespan, datetime, uuid

The Glean SDK provides some very handy higher-level metric types for specific data. If your data

GIFFT: These types of collection are mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions.

Events - Use Glean’s event

Telemetry Events are a lesser-used form of data collection in Firefox Desktop. Glean aimed to remove some of the stumbling blocks facing instrumentors when using events in the Glean event metric type:

  • Don’t worry about enabling event categories. In Glean all events are always on.

  • No more event name. Events in Glean follow the same category.name.metric_name naming structure that other metrics do.

  • No more method/object/value. Events in Glean are just their identifier and an extras key/value dictionary.

Since the two Event types aren’t that analogous you will need to decide if your event

  • Prefers to put its method/object/value in the extras dictionary

  • Prefers to fold its method/object/value into its identifier

GIFFT: Events are mirrorable back to Firefox Telemetry via the Glean Interface For Firefox Telemetry. See the guide for instructions.

Other: Environment, Crash Annotations, Use Counters, Etc - Ask on #glean:mozilla.org for assistance

Telemetry has a lot of collection subsystems build adjacent to those already mentioned. We have solutions for the common ones, but they are entirely dependent on the specific use case. Please reach out to us to explain it to us so we can help you either work within what Glean currently affords or design a new metric type for you.