Object

Record structured data.

Recording API

set

Sets an object metric to a specific value.

import org.mozilla.yourApplication.GleanMetrics.Party

var balloons = Party.BalloonsObject()
balloons.add(Party.BalloonsObjectItem(colour = "red", diameter = 5))
balloons.add(Party.BalloonsObjectItem(colour = "green"))
Party.balloons.set(balloons)

var balloons: Party.BalloonsObject = []
balloons.append(Party.BalloonsObjectItem(colour: "red", diameter: 5))
balloons.append(Party.BalloonsObjectItem(colour: "green"))
Party.balloons.set(balloons)

from glean import load_metrics
metrics = load_metrics("metrics.yaml")

balloons = metrics.BalloonsObject()
balloons.append(BalloonsObjectItem(colour="red", diameter=5))
balloons.append(BalloonsObjectItem(colour="green"))
metrics.party.balloons.set(balloons)

C++

Not yet implemented.

JavaScript

let balloons = [
  { colour: "red", diameter: 5 },
  { colour: "blue", diameter: 7 },
];
Glean.party.balloons.set(balloons);

Limits

  • Only objects matching the specified structure will be recorded

Recorded errors

  • invalid_value: if the passed value doesn't match the predefined structure

Testing API

testGetValue

Gets the recorded value for a given object metric.
Returns the data as a JSON object if data is stored.
Returns null 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.

import org.mozilla.yourApplication.GleanMetrics.Party

val snapshot = metric.testGetValue()!!
assertEquals(1, snapshot.jsonArray.size)

let snapshot = (try! Party.balloons.testGetValue()) as! [Any]
XCTAssertEqual(1, snapshot.size)

from glean import load_metrics
metrics = load_metrics("metrics.yaml")

snapshot = metrics.party.balloons.test_get_value()
assert 2 == len(snapshot)

C++

Not yet implemented.

JavaScript

// testGetValue will throw a data error on invalid value.
Assert.equal(
  [
    { colour: "red", diameter: 5 },
    { colour: "blue", diameter: 7 },
  ],
  Glean.party.balloons.testGetValue()
);

testGetNumRecordedErrors

Gets the number of errors recorded for a given text metric.

import org.mozilla.yourApplication.GleanMetrics.Party

assertEquals(
    0,
    Party.balloons.testGetNumRecordedErrors(ErrorType.INVALID_VALUE)
)

XCTAssertEqual(0, Party.balloons.testGetNumRecordedErrors(.invalidValue))

from glean import load_metrics
from glean.testing import ErrorType
metrics = load_metrics("metrics.yaml")

assert 0 == metrics.party.balloons.test_get_num_recorded_errors(
    ErrorType.INVALID_VALUE
)

Metric parameters

Example text metric definition:

party:
  balloons:
    type: object
    description: A collection of balloons
    bugs:
      - https://bugzilla.mozilla.org/TODO
    data_reviews:
      - http://example.com/reviews
    notification_emails:
      - CHANGE-ME@example.com
    expires: never
    structure:
      type: array
      items:
        type: object
        properties:
          colour:
            type: string
          diameter:
            type: number

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

Data questions

  • What is the crash stack after a Firefox main process crash?