UUID

UUIDs metrics are used to record values that uniquely identify some entity, such as a client id.

Recording API

generateAndSet

Sets a UUID metric to a randomly generated UUID value (UUID v4) .

import org.mozilla.yourApplication.GleanMetrics.User

// Generate a new UUID and record it
User.clientId.generateAndSet()

import org.mozilla.yourApplication.GleanMetrics.User;

// Generate a new UUID and record it
User.INSTANCE.clientId().generateAndSet();

// Generate a new UUID and record it
User.clientId.generateAndSet()

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

# Generate a new UUID and record it
metrics.user.client_id.generate_and_set()

use uuid::Uuid;
use glean_metrics::user;

// Generate a new UUID and record it
user::client_id.generate_and_set();

import * as user from "./path/to/generated/files/user.js";

user.clientId.generateAndSet();

C++

#include "mozilla/glean/GleanMetrics.h"

// Generate a new UUID and record it.
mozilla::glean::user::client_id.GenerateAndSet();

JavaScript

// Generate a new UUID and record it.
Glean.user.clientId.generateAndSet();

set

Sets a UUID metric to a specific value. Accepts any UUID version.

import org.mozilla.yourApplication.GleanMetrics.User

// Set a UUID explicitly
User.clientId.set(UUID.randomUUID())  // Set a UUID explicitly

import org.mozilla.yourApplication.GleanMetrics.User;

// Set a UUID explicitly
User.INSTANCE.clientId().set(UUID.randomUUID());

User.clientId.set(UUID())  // Set a UUID explicitly

import uuid

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

# Set a UUID explicitly
metrics.user.client_id.set(uuid.uuid4())

use uuid::Uuid;
use glean_metrics::user;

// Set a UUID explicitly
user::client_id.set(Uuid::new_v4());

import * as user from "./path/to/generated/files/user.js";

const uuid = "decafdec-afde-cafd-ecaf-decafdecafde";
user.clientId.set(uuid);

C++

#include "mozilla/glean/GleanMetrics.h"

// Set a specific value.
nsCString kUuid("decafdec-afde-cafd-ecaf-decafdecafde");
mozilla::glean::user::client_id.Set(kUuid);

JavaScript

// Set a specific value.
const uuid = "decafdec-afde-cafd-ecaf-decafdecafde";
Glean.user.clientId.set(uuid);

Recorded errors

  • invalid_value: if the value is set to a string that is not a UUID (only applies for dynamically-typed languages, such as Python).
  • invalid_type: if a non-string or non-UUID value is given.

Testing API

testGetValue

Gets the recorded value for a given UUID metric.
Returns a UUID if data is stored.
Returns a language-specific empty/null value if no data is stored.

import org.mozilla.yourApplication.GleanMetrics.User

// Was it the expected value?
assertEquals(uuid, User.clientId.testGetValue())

import org.mozilla.yourApplication.GleanMetrics.User;

// Was it the expected value?
assertEquals(uuid, User.INSTANCE.clientId().testGetValue());

// Was it the expected value?
XCTAssertEqual(uuid, try User.clientId.testGetValue())

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

# Was it the expected value?
assert uuid == metrics.user.client_id.test_get_value()

use uuid::Uuid;
use glean_metrics::user;

let u = Uuid::new_v4();
// Does it have the expected value?
assert_eq!(u, user::client_id.test_get_value(None).unwrap());

import * as user from "./path/to/generated/files/user.js";

const uuid = "decafdec-afde-cafd-ecaf-decafdecafde";
assert(uuid, await user.clientId.testGetValue());

C++

#include "mozilla/glean/GleanMetrics.h"

// Is it clear of errors?
ASSERT_TRUE(mozilla::glean::user::client_id.TestGetValue().isOk());
// Does it have an expected values?
ASSERT_STREQ(kUuid.get(), mozilla::glean::user::client_id.TestGetValue().unwrap().value().get());

JavaScript

const uuid = "decafdec-afde-cafd-ecaf-decafdecafde";
// testGetValue will throw NS_ERROR_LOSS_OF_SIGNIFICANT_DATA on error.
Assert.equal(Glean.user.clientId.testGetValue(), uuid);

testGetNumRecordedErrors

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

import org.mozilla.yourApplication.GleanMetrics.User

assertEquals(
    0,
    User.clientId.testGetNumRecordedErrors(ErrorType.INVALID_VALUE)
)

import org.mozilla.yourApplication.GleanMetrics.User;

assertEquals(
    0,
    User.INSTANCE.clientId().testGetNumRecordedErrors(ErrorType.INVALID_VALUE)
);

XCTAssertEqual(0, User.clientId.testGetNumRecordedErrors(.invalidValue))

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

from glean.testing import ErrorType

assert 0 == metrics.user.client_id.test_get_num_recorded_errors(
    ErrorType.INVALID_VALUE
)

use glean::ErrorType;
use glean_metrics::user;

assert_eq!(
  0,
  user::client_id.test_get_num_recorded_errors(
    ErrorType::InvalidValue
  )
);

import * as user from "./path/to/generated/files/user.js";
import { ErrorType } from "@mozilla/glean/error";

// Was the string truncated, and an error reported?
assert.strictEqual(
  0,
  await user.clientId.testGetNumRecordedErrors(ErrorType.InvalidValue)
);

Metric Parameters

You first need to add an entry for it to the metrics.yaml file:

user:
  client_id:
    type: uuid
    description: >
      A unique identifier for the client's profile
    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

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

Extra metric parameters

N/A

Data questions

  • A unique identifier for the client.

Reference