String List

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

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

Configuration

First you need to add an entry for the counter to the metrics.yaml file:

search:
engines:
type: string_list
description: >
Records the name of the enabled search engines.
...


API

import org.mozilla.yourApplication.GleanMetrics.Search

// Add them one at a time
engines.forEach {
}

// Set them in one go
Search.engines.set(engines)


There are test APIs available too:

import org.mozilla.yourApplication.GleanMetrics.Search

// Was anything recorded?
assertTrue(Search.engines.testHasValue())
// Does it have the expected value?
// IMPORTANT: It may have been truncated -- see "Limits" below
// Were any of the values too long, and thus an error was recorded?
assertEquals(1, Search.engines.testGetNumRecordedErrors(ErrorType.InvalidValue))

// Add them one at a time
for engine in engines {
}

// Set them in one go
Search.engines.set(engines)


There are test APIs available too:

@testable import Glean

// Was anything recorded?
XCTAssert(Search.engines.testHasValue())
// Does it have the expected value?
// IMPORTANT: It may have been truncated -- see "Limits" below
// Were any of the values too long, and thus an error was recorded?
XCTAssertEqual(1, Search.engines.testGetNumRecordedErrors(.invalidValue))

from glean import load_metrics

# Add them one at a time
for engine in engines:

# Set them in one go
metrics.search.engines.set(engines)


There are test APIs available too:

# Was anything recorded?
assert metrics.search.engines.test_has_value()
# Does it have the expected value?
# IMPORTANT: It may have been truncated -- see "Limits" below
# Were any of the values too long, and thus an error was recorded?
assert 1 == metrics.search.engines.test_get_num_recorded_errors(
ErrorType.INVALID_VALUE
)

using static Mozilla.YourApplication.GleanMetrics.Search;

// Set a string array into the metric.
Search.engines.Set(new string[] { "Google", "DuckDuckGo" });
// Add another string into the metric.


There are test APIs available too:

using static Mozilla.YourApplication.GleanMetrics.Search;

// Was anything recorded?
Assert.True(Search.engines.TestHasValue());
// Does the string list metric have the expected value?
// IMPORTANT: It may have been truncated -- see "Limits" below
var snapshot = Search.engines.TestGetValue();
Assert.Equal(3, Search.engines.Length);
Assert.Equal("DuckDuckGo", Search.engines[1]);
Assert.Equal("Baidu", Search.engines[2]);
// Was the string truncated, and an error reported?
Assert.Equal(
1,
Search.engines.TestGetNumRecordedErrors(
ErrorType.InvalidValue
)
);


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.

Examples

• The names of the enabled search engines.

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