Glean Parser

19.0.0 verified Mon Apr 27 auth: no python

Parser tools for Mozilla's Glean telemetry system. Version 19.0.0, released on a monthly cadence. Used to translate YAML-based metric definitions into language-specific bindings (Swift, Kotlin, Python, etc.) and to perform linting and validation.

pip install glean-parser

Common errors

error ModuleNotFoundError: No module named 'glean_parser' ↓

cause The package is not installed, or installed in a different environment.

fix

Run pip install glean-parser. Verify the environment with python -m pip list | grep glean-parser.

error ImportError: cannot import name 'translate' from 'glean_parser.util' ↓

cause The import path changed in v5. The function is now at `glean_parser.translate`.

fix

Use from glean_parser import translate instead.

error glean_parser.cli.main: error: unrecognized arguments: --coverage ↓

cause The `coverage` subcommand was removed in v19.

fix

Remove coverage usage. Use external testing coverage tools if needed.

error glean_parser.lint.LinterError: metric 'my.metric' is reserved ↓

cause The metric name conflicts with a reserved Glean identifier.

fix

Use option={"allow_reserved": False} to avoid this, or rename the metric. If intentional, pass allow_reserved=True (not recommended).

Warnings

breaking In v19, the `coverage` subcommand was removed entirely. If you relied on it, use external coverage tools. ↓

fix Remove any calls to `glean_parser coverage ...`. Check `glean_parser --help` for available commands.

deprecated The `--option` flag for `translate` is being replaced by structured arguments. In future versions, `options` dict will be the only way. ↓

fix Pass options as a dict: `translate(..., option={"allow_reserved": False})` instead of CLI-style `--option allow_reserved=false`.

gotcha Always use `allow_reserved=False` in production. Without it, reserved metric names may clash with Glean internals. ↓

fix Set `option={"allow_reserved": False}` when calling `translate`.

gotcha Event timestamp values in server templates changed in v19.0.0. Verify that your server-side ingestion expects the new format. ↓

fix Update server-side schema to match new timestamp handling. See PR #831.

Imports

translate

wrong

from glean_parser.util import translate

correct

from glean_parser import translate

translate moved to top-level module in v5

validate_ping
```
from glean_parser import validate_ping
```
lint_glean
wrong
```
from glean_parser.lint import glinter
```
correct
```
from glean_parser import lint_glean
```
lint_glean is the public API; glinter is internal and removed in v19

Quickstart

This example runs the translator on a single metrics.yaml file, outputting Kotlin bindings.

from glean_parser import translate

# Validate and translate a metrics.yaml file to Kotlin
translate.translate(
    input_filepaths=["metrics.yaml"],
    output_dir="./generated",
    option={"allow_reserved": False}
)