Strings
String metrics allow recording a Unicode string value with arbitrary content.
This metric type does not support recording JSON blobs
- please get in contact with the Glean team if you're missing a type.
Important
Be careful using arbitrary strings and make sure they can't accidentally contain identifying data (like directory paths or user input).
Recording API
set
Set a string metric to a specific value.
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")
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");
// 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")
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")
use glean_metrics::search_default;
// Record a value into the metric.
search_default::name.set("duck duck go");
// If it changed later, you can record the new value:
search_default::name.set("wikipedia");
import * as searchDefault from "./path/to/generated/files/searchDefault.js";
// 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");
C++
#include "mozilla/glean/GleanMetrics.h"
mozilla::glean::search_default::name.Set("wikipedia"_ns);
JavaScript
Glean.searchDefault.name.set("wikipedia");
Recorded errors
invalid_overflow
: if the string is too long. (Prior to Glean 31.5.0, this recorded aninvalid_value
).invalid_type
: if a non-string value is given.
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.
Testing API
testGetValue
Get the recorded value for a given string metric.
Returns the string if data is stored.
Returns a language-specific empty/null value if no data is stored.
The recorded value may have been truncated. See "Limits" section above.
import org.mozilla.yourApplication.GleanMetrics.SearchDefault
// Does the string metric have the expected value?
assertEquals("wikipedia", SearchDefault.name.testGetValue())
import org.mozilla.yourApplication.GleanMetrics.SearchDefault;
// Does the string metric have the expected value?
assertEquals("wikipedia", SearchDefault.INSTANCE.name().testGetValue());
// Does the string metric have the expected value?
XCTAssertEqual("wikipedia", SearchDefault.name.testGetValue())
from glean import load_metrics
metrics = load_metrics("metrics.yaml")
# Does the string metric have the expected value?
assert "wikipedia" == metrics.search_default.name.test_get_value()
use glean_metrics::search_default;
// Does the string metric have the expected value?
assert_eq!(6, search_default::name.test_get_value(None).unwrap());
import * as searchDefault from "./path/to/generated/files/searchDefault.js";
assert.strictEqual("wikipedia", await searchDefault.name.testGetValue());
C++
#include "mozilla/glean/GleanMetrics.h"
// Is it clear of errors?
ASSERT_TRUE(mozilla::glean::search_default::name.TestGetValue().isOk());
// Does it have the expected value?
ASSERT_STREQ(
"wikipedia",
mozilla::glean::search_default::name.TestGetValue().unwrap().value().get()
);
JavaScript
// Does it have the expected value?
// testGetValue will throw NS_ERROR_LOSS_OF_SIGNIFICANT_DATA on error.
Assert.equal("wikipedia", Glean.searchDefault.name.testGetValue());
testGetNumRecordedErrors
Gets the number of errors recorded for a given string metric.
import org.mozilla.yourApplication.GleanMetrics.SearchDefault
// Was the string truncated, and an error reported?
assertEquals(
0,
SearchDefault.name.testGetNumRecordedErrors(ErrorType.INVALID_OVERFLOW)
)
import org.mozilla.yourApplication.GleanMetrics.SearchDefault;
// Was the string truncated, and an error reported?
assertEquals(
0,
SearchDefault.INSTANCE.name().testGetNumRecordedErrors(ErrorType.INVALID_OVERFLOW)
);
// Was the string truncated, and an error reported?
XCTAssertEqual(0, SearchDefault.name.testGetNumRecordedErrors(.invalidOverflow))
from glean import load_metrics
metrics = load_metrics("metrics.yaml")
# Was the string truncated, and an error reported?
assert 0 == metrics.search_default.name.test_get_num_recorded_errors(
ErrorType.INVALID_OVERFLOW
)
use glean::ErrorType;
use glean_metrics::search_default;
// Was the string truncated, and an error reported?
assert_eq!(
0,
search_default::name.test_get_num_recorded_errors(
ErrorType::InvalidOverflow
)
);
import * as searchDefault from "./path/to/generated/files/searchDefault.js";
import { ErrorType } from "@mozilla/glean/error";
// Was the string truncated, and an error reported?
assert.strictEqual(
0,
await searchDefault.name.testGetNumRecordedErrors(ErrorType.InvalidOverflow)
);
Metric parameters
Example string metric definition:
controls:
refresh_pressed:
type: string
description: >
The name of the default 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
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
-
Record the operating system name with a value of
"android"
. -
Recording the device model with a value of
"SAMSUNG-SGH-I997"
.