URL

URL metrics allow recording URL-like1 strings.

This metric type does not support recording data URLs - please get in contact with the Glean SDK team if you're missing a type.

Important

Be careful using arbitrary URLs and make sure they can't accidentally contain identifying data (like directory paths, user input or credentials).

1

The Glean SDKs specifically do not validate if a URL is fully spec compliant, all the validations performed are the ones listed in the "Recorded errors" section of this page.

Recording API

set

Set a URL metric to a specific string value.

import org.mozilla.yourApplication.GleanMetrics.Search

Search.template.set("https://mysearchengine.com/")
import org.mozilla.yourApplication.GleanMetrics.Search;

Search.INSTANCE.template.set("https://mysearchengine.com/");
Search.template.set("https://mysearchengine.com")

// Swift's URL type is supported
let url = URL(string: "https://mysearchengine.com")!
Search.template.set(url: url)
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

metrics.search.template.set("https://mysearchengine.com/")

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

search::template.set("https://mysearchengine.com/");
}
import * as search from "./path/to/generated/files/search.js";

search.template.set("https://mysearchengine.com/");

setUrl

Set a URL metric to a specific URL value.

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

search.template.setUrl(new URL("https://mysearchengine.com/"));

Recorded errors

  • invalid_value:
    • If the URL passed does not start with a scheme followed by a : character.
    • If the URL passed uses the data: protocol.
  • invalid_overflow: If the URL passed is longer than 2048 characters (before encoding).

Limits

  • Fixed maximum URL length: 2048. Longer URLs are dropped.

Testing API

testGetValue

Gets the recorded value for a given URL metric as a (unencoded) string.

import org.mozilla.yourApplication.GleanMetrics.Search

assertEquals("https://mysearchengine.com/", Search.template.testGetValue())
import org.mozilla.yourApplication.GleanMetrics.Search

assertEquals("https://mysearchengine.com/", Search.INSTANCE.template.testGetValue());
@testable import Glean

XCTAssertEqual("https://mysearchengine.com/", try Search.template.testGetValue())
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

assert "https://mysearchengine.com/" == metrics.search.template.test_get_value()

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

assert_eq!("https://mysearchengine.com/", search::template.test_get_value(None).unwrap());
}
import * as search from "./path/to/generated/files/search.js";

assert.strictEqual("https://mysearchengine.com/", await search.template.testGetValue());

testHasValue

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

import org.mozilla.yourApplication.GleanMetrics.Search

assertTrue(Search.template.testHasValue())
import org.mozilla.yourApplication.GleanMetrics.Search

assertTrue(Search.INSTANCE.template.testHasValue());
@testable import Glean

XCTAssert(try Search.template.testHasValue())
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

assert metrics.search.template.test_has_value()

testGetNumRecordedErrors

Gets number of errors recorded for a given counter metric.

import org.mozilla.yourApplication.GleanMetrics.Search

assertEquals(0, Search.template.testGetNumRecordedErrors(ErrorType.InvalidValue))

assertEquals(0, Search.template.testGetNumRecordedErrors(ErrorType.InvalidOverflow))
import org.mozilla.yourApplication.GleanMetrics.Search;

assertEquals(
    0,
    Search.INSTANCE.template.testGetNumRecordedErrors(
        ErrorType.InvalidValue
    )
);

assertEquals(
    0,
    Search.INSTANCE.template.testGetNumRecordedErrors(
        ErrorType.InvalidOverflow
    )
);
@testable import Glean

XCTAssertEqual(0, Search.template.testGetNumRecordedErrors(.invalidValue))
XCTAssertEqual(0, Search.template.testGetNumRecordedErrors(.invalidOverflow))
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

assert 0 == metrics.search.template.test_get_num_recorded_errors(
    ErrorType.INVALID_VALUE
)

assert 0 == metrics.search.template.test_get_num_recorded_errors(
    ErrorType.INVALID_OVERFLOW
)

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

use glean_metrics;

assert_eq!(
  0,
  search::template.test_get_num_recorded_errors(
    ErrorType::InvalidValue
  )
);

assert_eq!(
  0,
  search::template.test_get_num_recorded_errors(
    ErrorType::InvalidOverflow
  )
);
}
import * as search from "./path/to/generated/files/search.js";
import { ErrorType } from "@mozilla/glean/<platform>";

assert.strictEqual(
  0,
  await search.template.testGetNumRecordedErrors(ErrorType.InvalidValue)
);
assert.strictEqual(
  0,
  await search.template.testGetNumRecordedErrors(ErrorType.InvalidOverflow)
);

Metric parameters

Example URL metric definition:

search:
  template:
    type: url
    description: >
      The base URL used to build the search query for the search engine.
    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
    data_sensitivity:
      - web_activity

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

Note on data_sensitivity of URL metrics

URL metrics can only either be on categories 3 or 4, namely "Web activity data" or "Highly sensitive data".

Extra metric parameters

N/A

Data questions

  • What is the base URL used to build the search query for the search engine?

Reference