Using the experiments API
The Glean SDKs support tagging all their pings with experiments annotations. The annotations are useful to report that experiments were active at the time the measurement were collected. The annotations are reported in the optional experiments
entry in the ping_info
section of all pings.
Experiment annotations are not persisted
The experiment annotations set through this API are not persisted by the Glean SDKs. The application or consuming library is responsible for setting the relevant experiment annotations at each run.
It's not required to define experiment IDs and branches
Experiment IDs and branches don't need to be pre-defined in the Glean SDK registry files. Please also note that the
extra
map is a non-nested arbitraryString
toString
map. It also has limits on the size of the keys and values defined below.
Recording API
setExperimentActive
Annotates Glean pings with experiment data.
// Annotate Glean pings with experiments data.
Glean.setExperimentActive(
experimentId = "blue-button-effective",
branch = "branch-with-blue-button",
extra: mapOf(
"buttonLabel" to "test"
)
)
// Annotate Glean pings with experiments data.
Glean.shared.setExperimentActive(
experimentId: "blue-button-effective",
branch: "branch-with-blue-button",
extra: ["buttonLabel": "test"]
)
from glean import Glean
Glean.set_experiment_active(
experiment_id="blue-button-effective",
branch="branch-with-blue-button",
extra={
"buttonLabel": "test"
}
)
let mut extra = HashMap::new();
extra.insert("buttonLabel".to_string(), "test".to_string());
glean::set_experiment_active(
"blue-button-effective".to_string(),
"branch-with-blue-button".to_string(),
Some(extra),
);
C++
At present there is no dedicated C++ Experiments API for Firefox Desktop
If you require one, please file a bug.
JavaScript
let FOG = Cc["@mozilla.org/toolkit/glean;1"].createInstance(Ci.nsIFOG);
FOG.setExperimentActive(
"blue-button-effective",
"branch-with-blue-button",
{"buttonLabel": "test"}
);
Limits
experimentId
,branch
, and the keys and values of theextra
field are fixed at a maximum length of 100 bytes. Longer strings are truncated. (Specifically, length is measured in the number of bytes when the string is encoded in UTF-8.)extra
map is limited to 20 entries. If passed a map which contains more elements than this, it is truncated to 20 elements. WARNING Which items are truncated is nondeterministic due to the unordered nature of maps. What's left may not necessarily be the first elements added.
Recorded errors
invalid_value
: If the values ofexperimentId
orbranch
are truncated for length, if the keys or values in theextra
map are truncated for length, or if theextra
map is truncated for the number of elements.
setExperimentInactive
Removes the experiment annotation. Should be called when the experiment ends.
Glean.setExperimentInactive("blue-button-effective")
Glean.shared.setExperimentInactive(experimentId: "blue-button-effective")
from glean import Glean
Glean.set_experiment_inactive("blue-button-effective")
glean::set_experiment_inactive("blue-button-effective".to_string());
C++
At present there is no dedicated C++ Experiments API for Firefox Desktop
If you require one, please file a bug.
JavaScript
let FOG = Cc["@mozilla.org/toolkit/glean;1"].createInstance(Ci.nsIFOG);
FOG.setExperimentInactive("blue-button-effective");
Testing API
testIsExperimentActive
Reveals if the experiment is annotated in Glean pings.
assertTrue(Glean.testIsExperimentActive("blue-button-effective"))
XCTAssertTrue(Glean.shared.testIsExperimentActive(experimentId: "blue-button-effective"))
from glean import Glean
assert Glean.test_is_experiment_active("blue-button-effective")
assert!(glean::test_is_experiment_active("blue-button-effective".to_string());
testGetExperimentData
Returns the recorded experiment data including branch and extras.
assertEquals(
"branch-with-blue-button", Glean.testGetExperimentData("blue-button-effective")?.branch
)
XCTAssertEqual(
"branch-with-blue-button",
Glean.testGetExperimentData(experimentId: "blue-button-effective")?.branch
)
from glean import Glean
assert (
"branch-with-blue-button" ==
Glean.test_get_experiment_data("blue-button-effective").branch
)
assert_eq!(
"branch-with-blue-button",
glean::test_get_experiment_data("blue-button-effective".to_string()).branch,
);
C++
At present there is no dedicated C++ Experiments API for Firefox Desktop
If you require one, please file a bug.
JavaScript
let FOG = Cc["@mozilla.org/toolkit/glean;1"].createInstance(Ci.nsIFOG);
Assert.equals(
"branch-with-blue-button",
FOG.testGetExperimentData("blue-button-effective").branch
);