Getting Started with Firefox Desktop Data

The remainder of this section section describes Firefox Desktop Telemetry which goes back in various forms for many years. Modern data collection is based on the Glean platform. Older mobile product data is slightly different again, and is described in Choosing a Mobile Dataset.

Firefox clients out in the wild send us data as pings. Main pings contain some combination of environment data (e.g. operating system, hardware, Firefox version), measurements (e.g. max number of open tabs, time spent running in JavaScript garbage collection), and events (note, though, that desktop events have largely been migrated to a separate event ping). We have quite a few different pings, but most of our data for Firefox Desktop comes in from main pings.

Measurement Types

When we need to measure specific things about clients, we use probes. A single ping will send in many different probes. There are two types of probes that we are interested in here: Histograms and Scalars.

You can search for and find more details about probes using the Probe Dictionary. It shows things like probe descriptions, when a probe started being collected, and whether it is collected on the release channel.

Histograms are bucketed counts. The Histograms.json file has the definitions for all histograms, which includes the minimum, maximum, and number of buckets. Any recorded value instead just increments its associated bucket. We have four main types of histograms:

  1. Boolean - Only two buckets, associated with true and false.
  2. Enumerated - Integer buckets, where usually each bucket has a label.
  3. Linear - Buckets are divided evenly between the minimum and maximum; e.g. [1-2] is a bucket, and so is [100-101].
  4. Exponential - Larger valued buckets cover a larger range; e.g. [1-2] is a bucket, and so is [100-200].

To see some of these in action, take a look at the Histogram Simulator.

Scalars are simply a single value. The Scalars.yaml file has the definitions for all scalars. These values can be integers, strings, or booleans.


The simplest way to start looking at probe data is to head over to or TMO for short.

From there, you will likely want either the Measurement Dashboard or the Evolution Dashboard. Using these dashboards you can compare a probe's value between populations, e.g. GC_MS for 64 bit vs. 32 bit, and even track it across builds.

The Measurement Dashboard is a snapshot, aggregating all the data from all chosen dimensions. The Y axis is % of samples, and the X axis is the bucket. You can compare between dimensions, but it does not give you the ability to see how data is changing over time. To investigate that you must use the Evolution Dashboard.

The Evolution Dashboard shows how the data changes over time. Choose which statistics you'd like to plot over time, e.g. Median or 95th percentile. The X axis is time, and the Y axis is the value for whichever statistic you've chosen. This dashboard, for example, shows how GC_MS is improving from nightly 53 to nightly 56! While the median is not changing much, the 95th percentile is trending down, indicating that long garbage collections are being shortened.

The X axis on the Evolution Dashboard shows either Build ID (a date), or Submission Date. The difference is that on any single date we might receive submissions from lots of builds, but aggregating by Build ID means we can be sure a change was because of a new build.

The second plot on the Evolution View is the number of pings we saw containing that probe (Metric Count).

TMO Caveats

  • Data is aggregated on a per-ping basis, meaning these dashboards cannot be used to say something definitive about users. Please repeat that to yourself. A trend in the evolution view may be caused not by a change affecting lots of users, but a change affecting one single user who is now sending 50% of the pings we see. And yes, that does happen.
  • Sometimes it looks like no data is there, but you think there should be. Check under advanced settings and check "Don't Sanitize" and "Don't Trim Buckets". If it's still not there, see getting help.
  • TMO Measurement Dashboards do not currently show release-channel data. Release-channel data ceased being aggregated as of Firefox 58. We're looking into ways of doing this correctly in the near future.

Where to go next