Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
docs
scripts
src
README.md
build.gradle
metrics.yaml
proguard-rules.pro

README.md

Android Components > Service > Glean

A client-side telemetry SDK for collecting metrics and sending them to Mozilla's telemetry service (eventually replacing service-telemetry).

Before using the library

Products using glean to collect telemetry must:

  • add documentation for any new metric collected with the library in its repository (see an example);
  • go through data review for the newly collected data by following this process;
  • provide a way for users to turn data collection off (e.g. providing settings to control Glean.setUploadEnabled()).

Usage

Setting up the dependency

Use Gradle to download the library from maven.mozilla.org (Setup repository):

implementation "org.mozilla.components:service-glean:{latest-version}"

Integrating with the build system

In order for Glean to work, a Python environment must be accessible at build time. This is done automatically by the com.jetbrains.python.envs plugin. The plugin must be manually enabled by adding the following plugins block at the top of the build.gradle file for your app module.

plugins {
    id "com.jetbrains.python.envs" version "0.0.26"
}

Right before the end of the same file, the glean build script must be included. This script can be referenced directly from the GitHub repo, as shown below:

apply from: 'https://github.com/mozilla-mobile/android-components/raw/v{latest-version}/components/service/glean/scripts/sdk_generator.gradle'

Important: the {latest-version} placeholder in the above link should be replaced with the version number of the glean library used by the project. For example, if version 0.34.2 is used, then the include directive becomes:

apply from: 'https://github.com/mozilla-mobile/android-components/raw/v0.34.2/components/service/glean/scripts/sdk_generator.gradle'

Initializing glean

Before any data collection can take place, glean must be initialized from the application. An excellent place to perform this operation is within the onCreate method of the class that extends Android's Application class.

class SampleApplication : Application() {

    override fun onCreate() {
        super.onCreate()

        // Initialize the Glean library. Ideally, this is the first thing that
        // must be done right after enabling logging.
        Glean.initialize(applicationContext)
    }
}

Once initialized, if collection is enabled, glean will automatically start collecting baseline metrics and sending its pings.

Glean should be initialized as soon as possible, and importantly, before any other libraries in the application start using Glean. Library code should never call Glean.initialize, since it should be called exactly once per application.

Adding new metrics

All metrics that your application collects must be defined in a metrics.yaml file. This file should be at the root of the application module (the same directory as the build.gradle file you updated). The format of that file is documented here. To learn more, see adding new metrics.

Important: as stated here, any new data collection requires documentation and data-review. This is also required for any new metric automatically collected by glean.

Testing metrics

In order to make testing metrics easier 'out of the box', all metrics include a set of test API functions in order to facilitate unit testing. These include functions to test whether a value has been stored, and functions to retrieve the stored value for validation. For more information, please refer to Unit testing glean metrics.

Providing UI to enable / disable metrics

Every application must provide a way to disable and re-enable data collection and upload. This is controlled with the glean.setUploadEnabled() method. The application should provide some form of user interface to call this method.

Debugging products using glean

Glean exports the GleanDebugActivity that can be used to toggle debugging features on or off. Users can invoke this special activity, at run-time, using the following adb command:

adb shell am start -n [package.name]/mozilla.components.service.glean.debug.GleanDebugActivity [extra keys]

Where the [package.name] is the product's package name as exported in the manifest file (e.g. org.mozilla.samples.glean for the glean sample application) and [extra keys] is a list of extra keys to be passed to the debug activity. See the documentation for the command line switches used to pass the extra keys. These are the currently supported keys:

key type description
logPings boolean (--ez) If set to true, glean dumps pings to logcat; defaults to false
sendPing string (--es) Sends the ping with the given name immediately.

For example, to direct the glean sample application to dump pings to logcat, and send the "metrics" ping immediately, the following command can be used:

adb shell am start -n org.mozilla.samples.glean/mozilla.components.service.glean.debug.GleanDebugActivity \
  --ez logPings true \
  --es sendPing metrics

Contact

To contact us you can:

License

This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/
You can’t perform that action at this time.