mozilla / glean-annotations

Annotations for Glean Metrics

Glean Annotations

This repository stores user-defined annotations against glean metrics: both those defined in applications (for example, "fenix" aka "Firefox for Android") as well as libraries like android-components.

The published set of annotations is available at: https://mozilla.github.io/glean-annotations/api.json

Documentation on how this repository works, as well as contribution information, is available at: https://mozilla.github.io/glean-annotations/

Local development

In general, the idea behind this repository is that most people will edit annotations from the Glean Dictionary. However, if you want to do local development the recommended setup process is to create a virtual environment and install the dependencies inside it. This requires a recent version of python (3.7+):

python3 -m venv venv/
source venv/bin/activate
pip install -r requirements.txt

After creating activating a virtual environment and installing the dependencies, run:

./scripts/create-api.py > api.json

This will create a JSON file which should be the same as the published set of annotations above.

To exit the virtual environment, use:

deactivate venv

glean-annotations's Issues

Glean dictionary is out of sync with this repo

Here's what I currently see on the Glean dictionary at this url:

Here is how the the repo's docs look at the latest commit on main: d11db7f

Report

Add annotations for changed Glean startup metrics

There was a recent change in the Glean startup metrics which we should document: many startup metrics are now obsolete and new ones should be used instead. The obsolete metrics aren't in the metrics.yaml file but will stay in the Glean Dictionary (and the data should continue to be accessible).

mozilla-mobile/fenix#19252

I can take this particular task on.

Document how to best include images in annotations

Right now we have at least 2 instances (see #169) where we link to GitHub-hosted images (because that's the most immediate way if you just drag'n'drop an image into the GitHub editor).

We should:

• probably pull those images into the repository
  • afaik github image hosting is stable, but who knows when that will go away
• Document what to do with images
• Stretch: Serve them through our github pages (the one that also hosts the JSON itself)

Validate API output against a JSON schema

We should create a simple JSON schema for the output of https://github.com/mozilla/glean-annotations/blob/main/scripts/create-api.py

@acmiyaguchi had some good suggestions for the format in #8 (comment)

You can use the probe scraper repository schema as an example: https://github.com/mozilla/probe-scraper/blob/master/schemas/repositories.json

Once the schema is created, the next step is to validate it, using something like python's jsonschema package. you should be able to hook it up to CI by adding a validation step in .circleci/config.yml

Feel free to reach out in #glean-dictionary on chat.mozilla.org if you have questions: https://chat.mozilla.org/#/room/#glean-dictionary:mozilla.org

Headings as anchor links?

On our new messaging-system docs page, we've added all the data that used to be here on firefox-source-docs.

Generally it works great, but there are a couple things that make the doc less useful than the original was. I can't show this on the original page since it's been removed, but see this page for example.

So the firefox-source-docs page has syntax highlighting for code blocks and a paragraph icon next to each heading that allows one to link to that specific section. The page is so long that it's hard to link to a specific item in the doc without it. Typing in an anchor link manually like #spotlight-pings doesn't work either.