Glean SDK

67.2.0 verified Mon Apr 27 auth: no python

Glean is a modern telemetry system by Mozilla for collecting, storing, and sending application metrics and pings. It provides a type-safe, cross-platform SDK with a metric API, automatic batching, and built-in pings. Current version is 67.2.0, with a regular release cadence aligned with Mozilla's release cycle.

pip install glean-sdk

Common errors

error glean_sdk is not defined ↓

cause Old import path using glean_sdk instead of glean.

fix

Use 'from glean import ...' instead of 'from glean_sdk import ...'.

error Glean has already been initialized ↓

cause Calling Glean.initialize() more than once in the same process.

fix

Guard initialization with a flag or ensure single call at startup.

error Invalid metric identifier: 'my_metric' ↓

cause Metric identifier must be in kebab-case (e.g., 'my.metric').

fix

Use valid identifier format like 'test.bool'.

error ImportError: cannot import name 'MetricsPing' from 'glean' ↓

cause MetricsPing was removed in version 60+.

fix

Remove MetricsPing; ping scheduling is automatic.

Warnings

breaking Starting from version 50.0.0, the import path changed from `glean_sdk` to `glean`. Old code using `import glean_sdk` will break. Update imports to `from glean import ...`. ↓

fix Replace all `from glean_sdk import ...` with `from glean import ...`.

breaking The `MetricsPing` class was removed in version 60.0.0 in favor of automatic ping scheduling. Code importing `MetricsPing` will break. ↓

fix Remove MetricsPing usage; pings are now scheduled automatically. Use `Glean.initialize(...)` without explicitly scheduling pings.

deprecated The `Glean.initialize()` parameter `data_dir` is deprecated since version 55.0.0. Use `Configuration.data_dir` instead. ↓

fix Pass `data_dir` inside `Configuration` object.

gotcha Glean must be initialized only once. Calling `Glean.initialize()` multiple times raises an error or does nothing silently. Ensure initialization happens early and only once. ↓

fix Initialize Glean at application startup, guarded by a flag or on first launch.

gotcha Metric identifiers must be kebab-case (e.g., 'category.name'). Using underscores or invalid characters will cause errors during metric registration. ↓

fix Ensure metric strings follow the '[a-z][a-z0-9-]{0,}[.][a-z][a-z0-9-]{0,}' pattern.

Imports

Glean
wrong
```
from glean_sdk import Glean
```
correct
```
from glean import Glean
```
Import directly from 'glean' for the main API

MetricsPing

wrong

from glean.metrics import MetricsPing

correct

from glean import MetricsPing

BooleanMetricType

from glean.metrics import BooleanMetricType

Quickstart

Minimal example initializing Glean with a configurable server endpoint and a boolean metric.

import os
import glean
from glean import Glean, Configuration, MetricsPing
from glean.metrics import BooleanMetricType

# Initialize Glean with a custom server endpoint
server_endpoint = os.environ.get('GLEAN_SERVER_ENDPOINT', 'https://example.com')
app_id = 'my-app'
Glean.initialize(
    application_id=app_id,
    application_version='1.0.0',
    upload_enabled=True,
    configuration=Configuration(
        server_endpoint=server_endpoint
    )
)
# Define a boolean metric
my_metric = BooleanMetricType(1, 'test.bool')
print('Glean initialized successfully')