Labeled Quantities

Labeled quantity metrics are used to record different related non-negative integer values. For example, the width and height of the display in pixels.

Do not use Labeled Quantity metrics for counting

If you need to count some things (e.g. the number of times buttons are pressed) prefer using the Labeled Counter metric type, which has a specific API for counting things.

Recording API

set

Sets a quantity metric to a specific value for the given label.

use glean_metrics::gfx;

gfx::display.get("width").set(width);
gfx::display.get("height").set(height);

Limits

  • Quantities must be non-negative integers or 0.

Recorded errors

  • invalid_value: if a negative value is passed in.
  • invalid_type: if a floating point or non-number value is given.
  • 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 quantity metric. Returns the quantity value if data is stored. Returns a language-specific empty/null value if no data is stored. Has an optional argument to specify the name of the ping you wish to retrieve data from, except in Rust where it's required. None or no argument will default to the first value found for send_in_pings.

use glean_metrics::gfx;

// Was anything recorded?
assert_eq!(433, gfx::display.get("width").test_get_value(None).unwrap());
assert_eq!(42, gfx::display.get("height").test_get_value(None).unwrap());

testGetNumRecordedErrors

Gets the number of errors recorded for a given label in a labeled quantity metric.

use glean::ErrorType;
use glean_metrics::gfx;

assert_eq!(
  0,
  gfx::display.get("width").test_get_num_recorded_errors(
    ErrorType::InvalidValue,
    None
  )
);
assert_eq!(
  0,
  gfx::display.get("height").test_get_num_recorded_errors(
    ErrorType::InvalidValue,
    None
  )
);

Metric parameters

Example quantity metric definition:

gfx:
  display:
    type: labeled_quantity
    description: >
      The dimensions of the display, in pixels.
      For one-dimensional displays, uses only "width".
      Two-dimensional displays add "height".
      3D displays gain "depth".
    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
    unit: pixels
    labels:
      - width
      - height
      - depth

For a full reference on metrics parameters common to all metric types, refer to the metrics YAML registry format reference page.

Extra metric parameters

unit

Labeled Quantities have the required unit parameter, which is a free-form string for documentation purposes.

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:

  • Conform to the label format.
  • Each label must have a maximum of 71 characters.
  • Each label must only contain printable ASCII characters.
  • This list itself is limited to 4096 labels.
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

  • What are the dimensions of the display, in pixels?

Limits

  • Labels must conform to the label format.
  • Each label must have a maximum of 71 characters.
  • Each label must only contain printable ASCII characters.
  • The list of labels is limited to:
    • 16 different dynamic labels if no static labels are defined. Additional labels will all record to the special label __other__.
    • 100 labels if specified as static labels in metrics.yaml, see Labels. Unknown labels will be recorded under the special label __other__.

Reference