Getting Started with Firefox on Glean (FOG)

This documentation is designed to be helpful to those who are

• New to data collection in Firefox Desktop,

• Experienced with data collection in Firefox Desktop, but not the Glean kind

• Those who are just interested in a refresher.

What is FOG?

Firefox on Glean (FOG) is the library that brings the Glean SDK, Mozilla’s modern data collection system, to Firefox Desktop.

FOG’s code is in toolkit/components/glean and is considered part of the Toolkit :: Telemetry module. Bugs against FOG can be filed in Bugzilla in the Toolkit product and the Telemetry component. (No bugs about adding new instrumentation, please. You can file those in the components that you want instrumented.) You can find folks who can help answer your questions about FOG in

• #glean:mozilla.org

• #telemetry:mozilla.org

• Slack#data-help

On top of the usual things Glean embedders supply (user engagement monitoring, network upload configuration, data upload preference watching, …) FOG supplies Firefox-Desktop-specific things:

• Privileged JS API

• C++ API

• IPC

• Test Preferences

• Support for xpcshell, browser-chrome mochitests, GTests, and rusttests

• about:glean

• …and more.

What do I need to know about Glean?

You use the APIs supplied by the Glean SDK to instrument Mozilla projects.

The unit of instrumentation is the metric. Recording the number of times a user opens a new tab? That’s a metric. Timing how long each JS garbage collector pass takes? Also a metric.

Glean has documentation about how to add a new metric that you should follow to learn how to add a metric to instrument Firefox Desktop. There are some peculiarities specific to Firefox Desktop that you’ll wish to review as well. Don’t forget to get Data Collection Review for any new or expanded data collections in mozilla projects.

By adding a metric you’ve told the Glean SDK what shape of instrumentation you want. And by using the metric’s APIs to instrument your code, you’ve put your interesting data into that metric. But how does the data leave Firefox Desktop and make it to Mozilla’s Data Pipeline?

Batches of related metrics are collected into pings which are submitted according to their specific schedules. If you don’t say otherwise, any non-event-metric will be sent in the built-in Glean “metrics” ping about once a day. (event metrics are sent in the “events” ping more frequently than that).

With data being sent to Mozilla’s Data Pipeline, how do you analyse it?

That’s an impossible question to answer completely without knowing a lot about what questions you want to answer. However, in general, if you want to see what data is being collected by your instrumentation, go to its page in Glean Dictionary and you’ll find links and information there about how to proceed.

Where do I learn more?

Here in the FOG User Documentation you will find FOG-specific details like how to write instrumentation tests, or how to use Glean APIs to mirror data to Telemetry.

Most of what you should have to concern yourself with, as an instrumentor, is documented in the Book of Glean. Such as its illuminating glossary, the list of all metric types, or the index of our long-running blog series This Week in Glean.

And for anything else you need help with, please find us in #glean:mozilla.org. We’ll be happy to help you learn more about FOG and Glean.