String List

Strings lists are used for recording a list of Unicode string values, such as the names of the enabled search engines.

Important

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

Recording API

add

Add a new string to the list.

import org.mozilla.yourApplication.GleanMetrics.Search

Search.engines.add("wikipedia")
Search.engines.add("duck duck go")
import org.mozilla.yourApplication.GleanMetrics.Search

Search.INSTANCE.engines().add("wikipedia")
Search.INSTANCE.engines().add("duck duck go")
Search.engines.add("wikipedia")
Search.engines.add("duck duck go")
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

metrics.search.engines.add("wikipedia")
metrics.search.engines.add("duck duck go")
use glean_metrics::search;

search::engines.add("wikipedia".to_string());
search::engines.add("duck duck go".to_string());

C++

#include "mozilla/glean/GleanMetrics.h"

mozilla::glean::search::engines.Add("wikipedia"_ns);
mozilla::glean::search::engines.Add("duck duck go"_ns);

JavaScript

Glean.search.engines.add("wikipedia");
Glean.search.engines.add("duck duck go");

Recorded errors

  • invalid_overflow: if the string is too long. (Prior to Glean 31.5.0, this recorded an invalid_value).
  • invalid_value: if the list is too long.

Limits

  • Fixed maximum string length: 50. Longer strings are truncated. This is measured in the number of bytes when the string is encoded in UTF-8.
  • Fixed maximum list length: 20 items. Additional strings are dropped.

set

Set the metric to a specific list of strings.

import org.mozilla.yourApplication.GleanMetrics.Search

Search.engines.set(listOf("wikipedia", "duck duck go"))
import org.mozilla.yourApplication.GleanMetrics.Search

Search.INSTANCE.engines().set(listOf("wikipedia", "duck duck go"))
Search.engines.set(["wikipedia", "duck duck go"])
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

metrics.search.engines.set(["wikipedia", "duck duck go"])
use glean_metrics::search;

search::engines.set(vec!["wikipedia".to_string(), "duck duck go".to_string()])

C++

#include "mozilla/glean/GleanMetrics.h"

mozilla::glean::search::engines.Set({"wikipedia"_ns, "duck duck go"_ns});

JavaScript

Glean.search.engines.set(["wikipedia", "duck duck go"]);

Recorded errors

  • invalid_overflow: if the string is too long. (Prior to Glean 31.5.0, this recorded an invalid_value).
  • invalid_value: if the list is too long.

Limits

  • Fixed maximum string length: 50. Longer strings are truncated. This is measured in the number of bytes when the string is encoded in UTF-8.
  • Fixed maximum list length: 20 items. Additional strings are dropped.

Testing API

testGetValue

Gets the recorded value for a given string list metric.

import org.mozilla.yourApplication.GleanMetrics.Search

assertEquals(listOf("Google", "DuckDuckGo"), Search.engines.testGetValue())
import org.mozilla.yourApplication.GleanMetrics.Search

assertEquals(
    Arrays.asList("Google", "DuckDuckGo"),
    Search.INSTANCE.engines().testGetValue()
)
@testable import Glean

XCTAssertEqual(["Google", "DuckDuckGo"], try Search.engines.testGetValue())
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

assert ["Google", "DuckDuckGo"] == metrics.search.engines.test_get_value()
use glean_metrics::search;

assert_eq!(
    vec!["Google".to_string(), "DuckDuckGo".to_string()],
    search::engines.test_get_value(None).unwrap()
);

C++

#include "mozilla/glean/GleanMetrics.h"

ASSERT_EQUAL(mozilla::glean::search::engines.TestGetValue().isOk());
nsTArray<nsCString> list = mozilla::glean::search::engines.TestGetValue().unwrap();
ASSERT_TRUE(list.Contains("wikipedia"_ns));
ASSERT_TRUE(list.Constains("duck duck go"_ns));

JavaScript

// testGetValue will throw NS_ERROR_LOSS_OF_SIGNIFICANT_DATA on error.
const engines = Glean.search.engines.testGetValue();
Assert.ok(engines.includes("wikipedia"));
Assert.ok(engines.includes("duck duck go"));

testHasValue

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

import org.mozilla.yourApplication.GleanMetrics.Search

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

assertTrue(Search.INSTANCE.engines().testHasValue())
@testable import Glean

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

assert metrics.search.engines.test_has_value()

testGetNumRecordedErrors

Gets number of errors recorded for a given string list metric.

import org.mozilla.yourApplication.GleanMetrics.Search

assertEquals(1, Search.engines.testGetNumRecordedErrors(ErrorType.InvalidValue))
import org.mozilla.yourApplication.GleanMetrics.Search

assertEquals(
    1, Search.INSTANCE.engines().testGetNumRecordedErrors(ErrorType.InvalidValue)
)
@testable import Glean

// Were any of the values too long, and thus an error was recorded?
XCTAssertEqual(1, Search.engines.testGetNumRecordedErrors(.invalidValue))
from glean import load_metrics
metrics = load_metrics("metrics.yaml")

assert 1 == metrics.search.engines.test_get_num_recorded_errors(
    ErrorType.INVALID_VALUE
)
use glean::ErrorType;
use glean_metrics::search;

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

Metric parameters

Example string list metric definition:

search:
  engines:
    type: string_list
    description: >
      Records the name of the enabled search engines.
    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

  • Which search engines are enabled?

Reference