Labeled Booleans

Labeled booleans are used to record different related boolean flags.

Configuration

For example, you may want to record a set of flags related to accessibility (a11y).

accessibility:
  features:
    type: labeled_boolean
    description: >
      a11y features enabled on the device. ...
    labels:
      - screen_reader
      - high_contrast
    ...

Note: 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.

API

Now you can use the labeled boolean from the application's code:

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

There are test APIs available too:

import org.mozilla.yourApplication.GleanMetrics.Accessibility
// Was anything recorded?
assertTrue(Accessibility.features["screen_reader"].testHasValue())
assertTrue(Accessibility.features["high_contrast"].testHasValue())
// Do the booleans have the expected values?
assertEquals(True, Accessibility.features["screen_reader"].testGetValue())
assertEquals(False, Accessibility.features["high_contrast"].testGetValue())
// Did we record any invalid labels?
assertEquals(0, Accessibility.features.testGetNumRecordedErrors(ErrorType.InvalidLabel))
Accessibility.features["screen_reader"].set(isScreenReaderEnabled())
Accessibility.features["high_contrast"].set(isHighContrastEnabled())

There are test APIs available too:

@testable import Glean

// Was anything recorded?
XCTAssert(Accessibility.features["screen_reader"].testHasValue())
XCTAssert(Accessibility.features["high_contrast"].testHasValue())
// Do the booleans have the expected values?
XCTAssertEqual(true, try Accessibility.features["screen_reader"].testGetValue())
XCTAssertEqual(false, try Accessibility.features["high_contrast"].testGetValue())
// Were there any invalid labels?
XCTAssertEqual(0, Accessibility.features.testGetNumRecordedErrors(.invalidLabel))
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()
)

There are test APIs available too:

# Was anything recorded?
assert metrics.accessibility.features["screen_reader"].test_has_value()
assert metrics.accessibility.features["high_contrast"].test_has_value()
# 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()
# Did we record any invalid labels?
assert 0 == metrics.accessibility.features.test_get_num_recorded_errors(
    ErrorType.INVALID_LABEL
)

Limits

  • Labels must conform to the label formatting regular expression.

  • Labels support lowercase alphanumeric characters; they additionally allow for dots (.), underscores (_) and/or hyphens (-).

  • Each label must have a maximum of 60 bytes, when encoded as UTF-8.

  • 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 aren't specified in the metrics.yaml, only 16 different dynamic labels may be used, after which the special value __other__ will be used.

Examples

  • Record a related set of boolean flags.

Recorded Errors

  • invalid_label: If the label contains invalid characters.

  • invalid_label: If the label exceeds the maximum number of allowed characters.

Reference