(“This Week in Glean” is a series of blog posts that the Glean Team at Mozilla is using to try to communicate better about our work. They could be release notes, documentation, hopes, dreams, or whatever: so long as it is inspired by Glean.) All “This Week in Glean” blog posts are listed in the TWiG index).
Basically, when a new piece of instrumentation is put up for code review (or before, or after), the instrumentor fills out a form and asks a volunteer Data Steward to review it. If the instrumentation (as explained in the filled-in form) is obviously in line with our privacy commitments to our users, the Data Steward gives it the go-ahead to ship.
(If it isn’t _obviously_ okay then we kick it up to our Trust Team to make the decision. They sit next to Legal, in case you need to find them.)
The Data Review Process and its forms are very generic. They’re designed to work for any instrumentation (tab count, bytes transferred, theme colour) being added to any project (Firefox Desktop, mozilla.org, Focus) and being collected by any data collection system (Firefox Telemetry, Crash Reporter, Glean). This is great for the process as it means we can use it and rely on it anywhere.
It isn’t so great for users _of_ the process. If you only ever write Data Reviews for one system, you’ll find yourself answering the same questions with the same answers every time.
And Glean makes this worse (better?) by including in its metrics definitions almost every piece of information you need in order to answer the review. So now you get to write the answers first in YAML and then in English during Data Review.
But no more! Introducing
glean_parser data-review and
mach data-review: command-line tools that will generate for you a Data Review Request skeleton with all the easy parts filled in. It works like this:
- Write your instrumentation, providing full information in the metrics definition.
python -m glean_parser data-review <bug_number> <list of metrics.yaml files>(or
mach data-review <bug_number>if you’re adding the instrumentation to Firefox Desktop).
- glean_parser will parse the metrics definitions files, pull out only the definitions that were added or changed in <bug_number>, and then output a partially-filled-out form for you.
Here’s an example. Say I’m working on bug 1664461 and add a new piece of instrumentation to Firefox Desktop:
fog.ipc: replay_failures: type: counter description: | The number of times the ipc buffer failed to be replayed in the parent process. bugs: - https://bugzilla.mozilla.org/show_bug.cgi?id=1664461 data_reviews: - https://bugzilla.mozilla.org/show_bug.cgi?id=1664461 data_sensitivity: - technical notification_emails: - email@example.com - firstname.lastname@example.org expires: never
I’m sure to fill in the `bugs` field correctly (because that’s important on its own _and_ it’s what glean_parser data-review uses to find which data I added), and have categorized the data_sensitivity. I also included a helpful description. (The data_reviews field currently points at the bug I’ll attach the Data Review Request for. I’d better remember to come back before I land this code and update it to point at the specific comment…)
Then I can simply use
mach data-review 1664461 and it spits out:
!! Reminder: it is your responsibility to complete and check the correctness of !! this automatically-generated request skeleton before requesting Data !! Collection Review. See https://wiki.mozilla.org/Data_Collection for details. DATA REVIEW REQUEST 1. What questions will you answer with this data? TODO: Fill this in. 2. Why does Mozilla need to answer these questions? Are there benefits for users? Do we need this information to address product or business requirements? TODO: Fill this in. 3. What alternative methods did you consider to answer these questions? Why were they not sufficient? TODO: Fill this in. 4. Can current instrumentation answer these questions? TODO: Fill this in. 5. List all proposed measurements and indicate the category of data collection for each measurement, using the Firefox data collection categories found on the Mozilla wiki. Measurement Name | Measurement Description | Data Collection Category | Tracking Bug ---------------- | ----------------------- | ------------------------ | ------------ fog_ipc.replay_failures | The number of times the ipc buffer failed to be replayed in the parent process. | technical | https://bugzilla.mozilla.org/show_bug.cgi?id=1664461 6. Please provide a link to the documentation for this data collection which describes the ultimate data set in a public, complete, and accurate way. This collection is Glean so is documented [in the Glean Dictionary](https://dictionary.telemetry.mozilla.org). 7. How long will this data be collected? This collection will be collected permanently. **TODO: identify at least one individual here** will be responsible for the permanent collections. 8. What populations will you measure? All channels, countries, and locales. No filters. 9. If this data collection is default on, what is the opt-out mechanism for users? These collections are Glean. The opt-out can be found in the product's preferences. 10. Please provide a general description of how you will analyze this data. TODO: Fill this in. 11. Where do you intend to share the results of your analysis? TODO: Fill this in. 12. Is there a third-party tool (i.e. not Telemetry) that you are proposing to use for this data collection? No.
As you can see, this Data Review Request skeleton comes partially filled out. Everything you previously had to mechanically fill out has been done for you, leaving you more time to focus on only the interesting questions like “Why do we need this?” and “How are you going to use it?”.
Also, this saves you from having to remember the URL to the Data Review Request Form Template each time you need it. We’ve got you covered.
And since this is part of Glean, this means this is already available to every project you can see here. This isn’t just a Firefox Desktop thing.
Hope this saves you some time! If you can think of other time-saving improvements we could add once to Glean so every Mozilla project can take advantage of, please tell us on Matrix.