Labeled Booleans

Labeled booleans are used to record different related boolean flags.

Recording API

set

Sets one of the labels in a labeled boolean metric to a specific value.

import org.mozilla.yourApplication.GleanMetrics.Accessibility

Accessibility.features["screen_reader"].set(isScreenReaderEnabled())
Accessibility.features["high_contrast"].set(isHighContrastEnabled())
import org.mozilla.yourApplication.GleanMetrics.Accessibility;

Acessibility.INSTANCE.features["screen_reader"].set(isScreenReaderEnabled());
Acessibility.INSTANCE.features["high_contrast"].set(isHighContrastEnabled());
Accessibility.features["screen_reader"].set(isScreenReaderEnabled())
Accessibility.features["high_contrast"].set(isHighContrastEnabled())
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

metrics.accessibility.features["screen_reader"].set(is_screen_reader_enabled())
metrics.accessibility.features["high_contrast"].set(is_high_contrast_enabled())

#![allow(unused)]
fn main() {
use glean_metrics;

accessibility::features.get("screen_reader").set(is_screen_reader_enabled());
accessibility::features.get("high_contrast").set(is_high_contrast_enabled());
}
import * as acessibility from "./path/to/generated/files/acessibility.js";

acessibility.features["screen_reader"].set(this.isScreenReaderEnabled());
acessibility.features["high_contrast"].set(this.isHighContrastEnabled());

C++

#include "mozilla/glean/GleanMetrics.h"

mozilla::glean::accessibility::features.Get("screen_reader"_ns).Set(true);
mozilla::glean::accessibility::features.Get("high_contrast"_ns).Set(false);

JavaScript

Glean.accessibility.features.screen_reader.set(true);
Glean.accessibility.features["high_contrast"].set(false);

Recorded Errors

  • invalid_label:
    • If the label contains invalid characters. Data is still recorded to the special label __other__.
    • If the label exceeds the maximum number of allowed characters. Data is still recorded to the special label __other__.

Testing API

testGetValue

Gets the recorded value for a given label in a labeled boolean metric.

import org.mozilla.yourApplication.GleanMetrics.Accessibility

// Do the booleans have the expected values?
assertEquals(True, Accessibility.features["screen_reader"].testGetValue())
assertEquals(False, Accessibility.features["high_contrast"].testGetValue())
import org.mozilla.yourApplication.GleanMetrics.Accessibility;

// Do the booleans have the expected values?
assertEquals(True, Acessibility.INSTANCE.features["screen_reader"].testGetValue());
assertEquals(False, Acessibility.INSTANCE.features["high_contrast"].testGetValue());
@testable import Glean

// Do the booleans have the expected values?
XCTAssertEqual(true, try Accessibility.features["screen_reader"].testGetValue())
XCTAssertEqual(false, try Accessibility.features["high_contrast"].testGetValue())
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

# Do the booleans have the expected values?
assert metrics.accessibility.features["screen_reader"].test_get_value()
assert not metrics.accessibility.features["high_contrast"].test_get_value()

#![allow(unused)]
fn main() {
use glean_metrics;

// Do the booleans have the expected values?
assert!(accessibility::features.get("screen_reader").test_get_value(None).unwrap());
assert!(!accessibility::features.get("high_contrast").test_get_value(None).unwrap());
}
import * as accessibility from "./path/to/generated/files/acessibility.js";

assert(await accessibility.features["screen_reader"].testGetValue());
assert(!(await accessibility.features["high_contrast"].testGetValue()));

C++

#include "mozilla/glean/GleanMetrics.h"

ASSERT_EQ(
    true,
    mozilla::glean::accessibility::features.Get("screen_reader"_ns).TestGetValue().unwrap().ref());
ASSERT_EQ(
    false,
    mozilla::glean::accessibility::features.Get("high_contrast"_ns).TestGetValue().unwrap().ref());

JavaScript

Assert.equal(true, Glean.accessibility.features["screen_reader"].testGetValue());
Assert.equal(false, Glean.accessibility.features.high_contrast.testGetValue());

testHasValue

Whether or not any value was recorded for a given label in a labeled boolean metric.

import org.mozilla.yourApplication.GleanMetrics.Accessibility

// Was anything recorded?
assertTrue(Accessibility.features["screen_reader"].testHasValue())
assertTrue(Accessibility.features["high_contrast"].testHasValue())
import org.mozilla.yourApplication.GleanMetrics.Accessibility;

// Was anything recorded?
assertEquals(True, Acessibility.INSTANCE.features["screen_reader"].testHasValue());
assertEquals(True, Acessibility.INSTANCE.features["high_contrast"].testHasValue());
@testable import Glean

// Was anything recorded?
XCTAssert(Accessibility.features["screen_reader"].testHasValue())
XCTAssert(Accessibility.features["high_contrast"].testHasValue())
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

# Was anything recorded?
assert metrics.accessibility.features["screen_reader"].test_has_value()
assert metrics.accessibility.features["high_contrast"].test_has_value()

testGetNumRecordedErrors

Gets the number of errors recorded for a given labeled boolean metric in total.

import org.mozilla.yourApplication.GleanMetrics.Accessibility

// Did we record any invalid labels?
assertEquals(0, Accessibility.features.testGetNumRecordedErrors(ErrorType.InvalidLabel))
import org.mozilla.yourApplication.GleanMetrics.Accessibility;

// Did we record any invalid labels?
assertEquals(0, Acessibility.INSTANCE.features.testGetNumRecordedErrors());
@testable import Glean

// Were there any invalid labels?
XCTAssertEqual(0, Accessibility.features.testGetNumRecordedErrors(.invalidLabel))
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

# Did we record any invalid labels?
assert 0 == metrics.accessibility.features.test_get_num_recorded_errors(
    ErrorType.INVALID_LABEL
)

#![allow(unused)]
fn main() {
use glean::ErrorType;

use glean_metrics;

// Did we record any invalid labels?
assert_eq!(
  1,
  accessibility::features.test_get_num_recorded_errors(
    ErrorType::InvalidLabel
  )
);
}
import * as accessibility from "./path/to/generated/files/acessibility.js";
import { ErrorType } from "@mozilla/glean/<platform>";

assert(
  1,
  await accessibility.features.testGetNumRecordedErrors(ErrorType.InvalidLabel)
);

Metric parameters

Example labeled boolean metric definition:

accessibility:
  features:
    type: labeled_boolean
    description: >
      a11y features enabled on the device.
    bugs:
      - https://bugzilla.mozilla.org/000000
    data_reviews:
      - https://bugzilla.mozilla.org/show_bug.cgi?id=000000#c3
    notification_emails:
      - me@mozilla.com
    expires: 2020-10-01
    labels:
      - screen_reader
      - high_contrast
      ...

Extra metric parameters

labels

Labeled metrics may have an optional labels parameter, containing a list of known labels. The labels in this list must match the following requirements:

Important

If the labels are specified in the metrics.yaml, using any label not listed in that file will be replaced with the special value __other__.

If the labels are not specified in the metrics.yaml, only 16 different dynamic labels may be used, after which the special value __other__ will be used.

Removing or changing labels, including their order in the registry file, is permitted. Avoid reusing labels that were removed in the past. It is best practice to add documentation about removed labels to the description field so that analysts will know of their existence and meaning in historical data. Special care must be taken when changing GeckoView metrics sent through the Glean SDK, as the index of the labels is used to report Gecko data through the Glean SDK.

Data questions

  • Which accessibility features are enabled?

Reference