Labeled Strings
Labeled strings record multiple Unicode string values, each under a different label.
Recording API
set
Sets one of the labels in a labeled string metric to a specific value.
import org.mozilla.yourApplication.GleanMetrics.Login
Login.errorsByStage["server_auth"].set("Invalid password")
import org.mozilla.yourApplication.GleanMetrics.Login;
Login.INSTANCE.errorsByStage["server_auth"].set("Invalid password");
Login.errorsByStage["server_auth"].set("Invalid password")
from glean import load_metrics
metrics = load_metrics("metrics.yaml")
metrics.login.errors_by_stage["server_auth"].set("Invalid password")
#![allow(unused)] fn main() { use glean_metrics; login::errors_by_stage.get("server_auth").set("Invalid password"); }
import * as login from "./path/to/generated/files/login.js";
login.errorsByStage["server_auth"].set("Invalid password");
C++
#include "mozilla/glean/GleanMetrics.h"
mozilla::glean::login::errors_by_stage.Get("server_auth"_ns).Set("Invalid password"_ns);
JavaScript
Glean.login.errorsByStage["server_auth"].set("Invalid password");
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.
Recorded Errors
invalid_overflow
: if the string is too long. (Prior to Glean 31.5.0, this recorded aninvalid_value
).invalid_label
:- If the label contains invalid characters. Data is still recorded to the special label
__other__
. - If the label exceeds the maximum number of allowed characters. Data is still recorded to the special label
__other__
.
- If the label contains invalid characters. Data is still recorded to the special label
invalid_type
: if a non-string value is given.
Testing API
testGetValue
Gets the recorded value for a given label in a labeled string metric.
import org.mozilla.yourApplication.GleanMetrics.Login
// Does the metric have the expected value?
assertTrue(Login.errorsByStage["server_auth"].testGetValue())
import org.mozilla.yourApplication.GleanMetrics.Login;
// Does the metric have the expected value?
assertTrue(Login.INSTANCE.errorsByStage["server_auth"].testGetValue());
// Does the metric have the expected value?
XCTAssert(Login.errorsByStage["server_auth"].testGetValue())
from glean import load_metrics
metrics = load_metrics("metrics.yaml")
# Does the metric have the expected value?
assert "Invalid password" == metrics.login.errors_by_stage["server_auth"].testGetValue())
#![allow(unused)] fn main() { use glean_metrics; // Does the metric have the expected value? assert!(login::errors_by_stage.get("server_auth").test_get_value()); }
import * as login from "./path/to/generated/files/login.js";
// Does the metric have the expected value?
assert.strictEqual("Invalid password", await metrics.login.errorsByStage["server_auth"].testGetValue())
C++
#include "mozilla/glean/GleanMetrics.h"
ASSERT_STREQ("Invalid password",
mozilla::glean::login::errors_by_stage.Get("server_auth"_ns)
.TestGetValue()
.unwrap()
.ref()
.get());
JavaScript
Assert.equal("Invalid password", Glean.login.errorsByStage["server_auth"].testGetValue());
testHasValue
Whether or not any value was recorded for a given label in a labeled string metric.
import org.mozilla.yourApplication.GleanMetrics.Login
// Was anything recorded?
assertTrue(Login.errorsByStage["server_auth"].testHasValue())
import org.mozilla.yourApplication.GleanMetrics.Login;
// Was anything recorded?
assertTrue(Login.INSTANCE.errorsByStage["server_auth"].testHasValue());
// Was anything recorded?
XCTAssert(Login.errorsByStage["server_auth"].testHasValue())
# Was anything recorded?
assert metrics.login.errors_by_stage["server_auth"].test_has_value()
testGetNumRecordedErrors
Gets the number of errors recorded for a given labeled string metric in total.
import org.mozilla.yourApplication.GleanMetrics.Login
// Were there any invalid labels?
assertEquals(0, Login.errorsByStage.testGetNumRecordedErrors(ErrorType.InvalidLabel))
import org.mozilla.yourApplication.GleanMetrics.Login;
// Were there any invalid labels?
assertEquals(0, Login.INSTANCE.errorsByStage.testGetNumRecordedErrors(ErrorType.InvalidLabel));
// Were there any invalid labels?
XCTAssertEqual(0, Login.errorsByStage.testGetNumRecordedErrors(.invalidLabel))
from glean import load_metrics
metrics = load_metrics("metrics.yaml")
# Were there any invalid labels?
assert 0 == metrics.login.errors_by_stage.test_get_num_recorded_errors(
ErrorType.INVALID_LABEL
)
#![allow(unused)] fn main() { use glean::ErrorType; use glean_metrics; // Were there any invalid labels? assert_eq!( 0, login::errors_by_stage.test_get_num_recorded_errors( ErrorType::InvalidLabel ) ); }
import * as login from "./path/to/generated/files/login.js";
import { ErrorType } from "@mozilla/glean/<platform>";
// Were there any invalid labels?
assert(
0,
await login.errorsByStage.testGetNumRecordedErrors(ErrorType.InvalidLabel)
);
Metric parameters
Example labeled boolean metric definition:
login:
errors_by_stage:
type: labeled_string
description: Records the error type, if any, that occur in different stages of the login process.
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
labels:
- server_auth
- enter_email
...
Extra metric parameters
labels
Labeled metrics may have an optional labels
parameter, containing a list of known labels.
The labels in this list must match the following requirements:
-
Conform to the label formatting regular expression.
-
Each label must have a maximum of 60 bytes, when encoded as UTF-8.
-
This list itself is limited to 100 labels.
Important
If the labels are specified in the
metrics.yaml
, using any label not listed in that file will be replaced with the special value__other__
.If the labels are not specified in the
metrics.yaml
, only 16 different dynamic labels may be used, after which the special value__other__
will be used.
Removing or changing labels, including their order in the registry file, is permitted. Avoid reusing labels that were removed in the past. It is best practice to add documentation about removed labels to the description field so that analysts will know of their existence and meaning in historical data. Special care must be taken when changing GeckoView metrics sent through the Glean SDK, as the index of the labels is used to report Gecko data through the Glean SDK.
Data questions
- What kinds of errors occurred at each step in the login process?
Reference
- Swift API docs:
LabeledMetricType
,StringMetricType
- Python API docs:
LabeledMetricBase
,StringMetricType
- Rust API docs:
LabeledMetric
,StringMetricType
- JavaScript API docs:
LabeledMetricType
,StringMetricType