Quantity

Used to record a single non-negative integer value or 0. For example, the width of the display in pixels.

Do not use Quantity for counting

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

Recording API

set

Sets a quantity metric to a specific value.

import org.mozilla.yourApplication.GleanMetrics.Display

Display.width.set(width)
import org.mozilla.yourApplication.GleanMetrics.Display;

Display.INSTANCE.width.set(width);
Display.width.set(width)
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

metrics.display.width.set(width)
import * as display from "./path/to/generated/files/display.js";

display.width.set(window.innerHeight);

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

display::width.set(width);
}

C++

#include "mozilla/glean/GleanMetrics.h"

mozilla::glean::display::width.Set(innerHeight);

JavaScript

Glean.display.width.set(innerHeight);

Limits

  • Quantities must be non-negative integers or 0.

Recorded errors

Testing API

testGetValue

Gets the recorded value for a given quantity metric.

import org.mozilla.yourApplication.GleanMetrics.Display

// Does the quantity have the expected value?
assertEquals(6, Display.width.testGetValue())
import org.mozilla.yourApplication.GleanMetrics.Display;

// Was anything recorded?
assertTrue(Display.INSTANCE.width.testHasValue());
// Does the quantity have the expected value?
assertEquals(6, Display.INSTANCE.width.testGetValue());
@testable import Glean

// Does the quantity have the expected value?
XCTAssertEqual(6, try Display.width.testGetValue())
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

# Does the quantity have the expected value?
assert 6 == metrics.display.width.test_get_value()
import * as display from "./path/to/generated/files/display.js";

assert.strictEqual(433, await display.width.testGetValue());

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

// Was anything recorded?
assert!(display::width.test_get_value(None).is_some());
}

C++

#include "mozilla/glean/GleanMetrics.h"

ASSERT_TRUE(mozilla::glean::display::width.TestGetValue().isOk());
ASSERT_EQ(433, mozilla::glean::display::width.TestGetValue().unwrap().value());

JavaScript

// testGetValue will throw NS_ERROR_LOSS_OF_SIGNIFICANT_DATA on error.
Assert.equal(433, Glean.display.width.testGetValue());

testHasValue

Whether or not any value was recorded for a given quantity metric.

import org.mozilla.yourApplication.GleanMetrics.Display

// Was anything recorded?
assertTrue(Display.width.testHasValue())
import org.mozilla.yourApplication.GleanMetrics.Display;

// Was anything recorded?
assertTrue(Display.INSTANCE.width.testHasValue());
);
@testable import Glean

// Was anything recorded?
XCTAssert(Display.width.testHasValue())
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

# Was anything recorded?
assert metrics.display.width.test_has_value()

testGetNumRecordedErrors

Gets number of errors recorded for a given quantity metric.

import org.mozilla.yourApplication.GleanMetrics.Display

// Did it record an error due to a negative value?
assertEquals(1, Display.width.testGetNumRecordedErrors(ErrorType.InvalidValue))
import org.mozilla.yourApplication.GleanMetrics.Display;

// Did the quantity record a negative value?
assertEquals(
    1, Display.INSTANCE.width.testGetNumRecordedErrors(ErrorType.InvalidValue)
);
@testable import Glean

// Did the quantity record a negative value?
XCTAssertEqual(1, Display.width.testGetNumRecordedErrors(.invalidValue))
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

# Did the quantity record an negative value?
from glean.testing import ErrorType
assert 1 == metrics.display.width.test_get_num_recorded_errors(
    ErrorType.INVALID_VALUE
)
import * as display from "./path/to/generated/files/display.js";
import { ErrorType } from "@mozilla/glean/<platform>";

assert.strictEqual(
  0,
  await display.width.testGetNumRecordedErrors(ErrorType.InvalidValue)
);

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

use glean_metrics;

assert_eq!(
  1,
  display::width.test_get_num_recorded_errors(
    ErrorType::InvalidValue
  )
);
}

Metric parameters

Example quantity metric definition:

controls:
  refresh_pressed:
    type: quantity
    description: >
      The width of the display, in pixels.
    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

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

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

Data questions

  • What is the width of the display, in pixels?

Reference