URL

URL metrics allow recording URL-like1 strings.

This metric type does not support recording data URLs - please get in contact with the Glean 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/")

use glean_metrics::search;

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

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

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

C++

#include "mozilla/glean/GleanMetrics.h"

mozilla::glean::search::template.Set("https://mysearchengine.com/"_ns);

JavaScript

Glean.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 8192 characters (before encoding).
  • invalid_type: if a non-string value is given.

Limits

  • Fixed maximum URL length: 8192. Longer URLs are truncated and recorded along with an invalid_overflow error.

Testing API

testGetValue

Gets the recorded value for a given URL metric as a (unencoded) string.
Returns a URL 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.

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());

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()

use glean_metrics::search;

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());

testGetNumRecordedErrors

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

import org.mozilla.yourApplication.GleanMetrics.Search

assertEquals(0, Search.template.testGetNumRecordedErrors(ErrorType.INVALID_VALUE))
assertEquals(0, Search.template.testGetNumRecordedErrors(ErrorType.INVALID_OVERFLOW))

import org.mozilla.yourApplication.GleanMetrics.Search;

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

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

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
)

use glean::ErrorType;
use glean_metrics::search;

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/error";

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 "Stored Content & Communications" 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