Strings
This allows recording a Unicode string value with arbitrary content.
Note: Be careful using arbitrary strings and make sure they can't accidentally contain identifying data (like directory paths or user input).
Note: This is does not support recording JSON blobs - please get in contact with the Telemetry team if you're missing a type.
Configuration
Say you're adding a metric to find out what the default search in a browser is. First you need to add an entry for the metric to the metrics.yaml
file:
search.default:
name:
type: string
description: >
The name of the default search engine.
lifetime: application
...
API
import org.mozilla.yourApplication.GleanMetrics.SearchDefault
// Record a value into the metric.
SearchDefault.name.set("duck duck go")
// If it changed later, you can record the new value:
SearchDefault.name.set("wikipedia")
There are test APIs available too:
import org.mozilla.yourApplication.GleanMetrics.SearchDefault
// Was anything recorded?
assertTrue(SearchDefault.name.testHasValue())
// Does the string metric have the expected value?
// IMPORTANT: It may have been truncated -- see "Limits" below
assertEquals("wikipedia", SearchDefault.name.testGetValue())
// Was the string truncated, and an error reported?
assertEquals(1, SearchDefault.name.testGetNumRecordedErrors(ErrorType.InvalidValue))
import org.mozilla.yourApplication.GleanMetrics.SearchDefault;
// Record a value into the metric.
SearchDefault.INSTANCE.name.set("duck duck go");
// If it changed later, you can record the new value:
SearchDefault.INSTANCE.name.set("wikipedia");
There are test APIs available too:
import org.mozilla.yourApplication.GleanMetrics.SearchDefault
// Was anything recorded?
assertTrue(SearchDefault.INSTANCE.name.testHasValue());
// Does the string metric have the expected value?
// IMPORTANT: It may have been truncated -- see "Limits" below
assertEquals("wikipedia", SearchDefault.INSTANCE.name.testGetValue());
// Was the string truncated, and an error reported?
assertEquals(
1,
SearchDefault.INSTANCE.name.testGetNumRecordedErrors(
ErrorType.InvalidValue
)
);
// Record a value into the metric.
SearchDefault.name.set("duck duck go")
// If it changed later, you can record the new value:
SearchDefault.name.set("wikipedia")
There are test APIs available too:
@testable import Glean
// Was anything recorded?
XCTAssert(SearchDefault.name.testHasValue())
// Does the string metric have the expected value?
// IMPORTANT: It may have been truncated -- see "Limits" below
XCTAssertEqual("wikipedia", try SearchDefault.name.testGetValue())
// Was the string truncated, and an error reported?
XCTAssertEqual(1, SearchDefault.name.testGetNumRecordedErrors(.invalidValue))
from glean import load_metrics
metrics = load_metrics("metrics.yaml")
# Record a value into the metric.
metrics.search_default.name.set("duck duck go")
# If it changed later, you can record the new value:
metrics.search_default.name.set("wikipedia")
There are test APIs available too:
# Was anything recorded?
assert metrics.search_default.name.test_has_value()
# Does the string metric have the expected value?
# IMPORTANT: It may have been truncated -- see "Limits" below
assert "wikipedia" == metrics.search_default.name.test_get_value()
# Was the string truncated, and an error reported?
assert 1 == metrics.search_default.name.test_get_num_recorded_errors(
ErrorType.INVALID_VALUE
)
using static Mozilla.YourApplication.GleanMetrics.SearchDefault;
// Record a value into the metric.
SearchDefault.name.Set("duck duck go");
// If it changed later, you can record the new value:
SearchDefault.name.Set("wikipedia");
There are test APIs available too:
using static Mozilla.YourApplication.GleanMetrics.SearchDefault;
// Was anything recorded?
Assert.True(SearchDefault.name.TestHasValue());
// Does the string metric have the expected value?
// IMPORTANT: It may have been truncated -- see "Limits" below
Assert.Equal("wikipedia", SearchDefault.name.TestGetValue());
// Was the string truncated, and an error reported?
Assert.Equal(
1,
SearchDefault.name.TestGetNumRecordedErrors(
ErrorType.InvalidValue
)
);
Note: C++ APIs are only available in Firefox Desktop.
#include "mozilla/glean/GleanMetrics.h"
mozilla::glean::search_default::name.Set("wikipedia"_ns);
There are test APIs available too:
#include "mozilla/glean/GleanMetrics.h"
// Does it have the expected value?
ASSERT_STREQ(
"wikipedia",
mozilla::glean::search_default::name.TestGetValue().value().get()
);
// Did it run across any errors?
// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
Note: JS APIs are currently only available in Firefox Desktop. General JavaScript support is coming soon via the Glean.js project.
Glean.searchDefault.name.set("wikipedia");
There are test APIs available too:
Assert.equal("wikipedia", Glean.searchDefault.name.testGetValue());
// Did it run across any errors?
// TODO: https://bugzilla.mozilla.org/show_bug.cgi?id=1683171
Limits
- Fixed maximum string length: 100. Longer strings are truncated. This is measured in the number of bytes when the string is encoded in UTF-8.
Examples
-
Record the operating system name with a value of
"android"
. -
Recording the device model with a value of
"SAMSUNG-SGH-I997"
.
Recorded errors
invalid_overflow
: if the string is too long. (Prior to Glean 31.5.0, this recorded aninvalid_value
).