Toggling collection status

The Glean SDKs provide an API for toggling Glean's collection status after initialization.

Applications instrumented with Glean are expected to provide some form of user interface to allow for toggling the collection status.

setUploadEnabled is deprecated since Glean v63.0.0

Prior to Glean v63.0.0 this API was called setUploadEnabled. setUploadEnabled is now deprecated and replaced by setCollectionEnabled. It behaves the same way with respect to built-in pings and custom pings, unless those are marked with follows_collection_enabled: false. See TODO: the collection-enabled documentation for details.

Disabling collection

When collection is disabled, the Glean SDK will perform the following tasks:

1. Submit a deletion-request ping.
2. Cancel scheduled ping uploads.
3. Clear metrics and pings data from the client, except for the first_run_date metric.

While collection is disabled, metrics aren't recorded and no data is uploaded.

Enabling collection

When collection is enabled, the Glean SDK will re-initialize its core metrics. The only core metric that is not re-initialized is the first_run_date metric.

While collection is enabled all metrics are recorded as expected and pings are sent to the telemetry servers.

API

Glean.setCollectionEnabled(boolean)

Enables or disables collection.

If called prior to initialize this function is a no-op.

If the collection state is not actually changed in between calls to this function, it is also a no-op.

import mozilla.telemetry.glean.Glean

open class MainActivity : AppCompatActivity() {
    override fun onCreate() {
        // ...

        uploadSwitch.setOnCheckedChangeListener { _, isChecked ->
            if (isChecked) {
                Glean.setCollectionEnabled(true)
            } else {
                Glean.setCollectionEnabled(false)
            }
        }
    }
}

import mozilla.telemetry.glean.Glean

Glean.INSTANCE.setCollectionEnabled(false);

import Glean
import UIKit

class ViewController: UIViewController {
    @IBOutlet var enableSwitch: UISwitch!

    // ...

    @IBAction func enableToggled(_: Any) {
        Glean.shared.setCollectionEnabled(enableSwitch.isOn)
    }
}

from glean import Glean

Glean.set_collection_enabled(false)

use glean;

glean::set_collection_enabled(false);

import Glean from "@mozilla/glean/web";

const uploadSwitch = document.querySelector("input[type=checkbox].upload-switch");
uploadSwitch.addEventListener("change", event => {
    if (event.target.checked) {
        Glean.setUploadEnabled(true);
    } else {
        Glean.setUploadEnabled(false);
    }
});

Reference

• Swift API docs
• Python API docs
• Rust API docs
• JavaScript API docs