Removing Telemetry Probes

We will be removing the Legacy Telemetry data collection system in the future. Before we do that, we must stop using it.

Preconditions

1. Are you reasonably certain no one is using this data from Legacy-Telemetry-sent pings in analyses?

   • You don’t have to be absolutely certain: the data is also being reported via Glean, so it’ll still be available to analyses if someone needs it. But if it’s presently under active use, it’ll add more work to someone’s day if you remove it before they’ve moved their analyses.

   • If you are absolutely certain that the data’s not being used at all, you can remove the instrumentation from both Glean and Legacy Telemetry by

     1. Following the instructions for removing the Legacy Telemetry probe

     2. Removing the Glean metric definition from metrics.yaml

     3. Removing the instrumenting code that references the Glean metric

Histograms, Scalars, or Events

To remove a Legacy Telemetry Histogram, Scalar, or Event, you must:

0. Identify and locate the Glean metrics and Legacy Telemetry probes involved.

   • The Glean metrics will be defined in a metrics.yaml file in your component.

   • The Legacy Telemetry probes will be named in the telemetry_mirror field of the Glean metrics’ definitions.

1. Remove the probe definition from toolkit/components/telemetry/Histograms.json, toolkit/components/telemetry/Scalars.yaml, or toolkit/components/telemetry/Events.yaml.

   • If some Histograms you are removing are especially old, you might find them referenced in one or more places in toolkit/components/telemetry/histogram-allowlists.json as well. Remove them from there, too.

2. Remove the telemetry_mirror fields from the Glean metrics’ definitions in metrics.yaml.

   • If you don’t, a full build will fail with a message like HistogramGIFFTMap.cpp:####:##: error: no member named 'THE_HISTOGRAM_ID' in 'mozilla::Telemetry::HistogramID'...

3. Perform a full (compiled) build and check test_mirrors.py

   • ./mach build && ./mach test toolkit/components/telemetry/tests/python/test_mirrors.py

   • This should catch most kinds of mistakes in the preceding steps.

4. Convert your instrumentation tests to test the Glean metrics instead of the now-removed Legacy Telemetry probes.

   • Consult the section on migrating tests for more details.

Environment Fields

To remove a Legacy Telemetry Environment field,

0. Ensure you aren’t removing any sections that are required in the schema.

1. Remove the code in toolkit/components/telemetry/app/TelemetryEnvironment.sys.mjs that sets its value.

2. Remove the code in toolkit/components/telemetry/tests/unit/test_TelemetryEnvironment.js and toolkit/components/telemetry/tests/unit/test_TelemetryEnvironment_search.js that tests it.

3. Remove the documentation in toolkit/components/telemetry/docs/data/environment.rst.

Custom Pings

To remove a Legacy Telemetry custom ping (one that uses TelemetryController.submitExternalPing(...)),

1. Remove the code

2. Remove the tests

3. Move the documentation in toolkit/components/telemetry/docs/data to toolkit/components/telemetry/docs/obsolete and append the word “(obsolete)” to the doc’s title.

Migrating Tests

Testing Glean instrumentation in Firefox Desktop is straightforward: for metrics you will use testGetValue() and for pings you will use testSubmission(). Please familiarize yourself with the instrumentation testing docs.

Specific changes you may have to make include:

• XPCShell tests need to manually initialize FOG, or they will freeze on the first testGetValue() call.

  • bug 1756055 hopes to change that.

  • Until then, add_setup(function () { do_get_profile(); Services.fog.initializeFOG(); });

• Instead of clearing via getting snapshots with aClearStore = true, clear Glean’s stored data with Services.fog.testResetFOG(); (JS), or by using the FOGFixture googletest fixture (C++).

• Instead of snapshotting all Histograms, all Events, or all Scalars, you should instead access the metric individually and call testGetValue().

  • Though event records returned by a Glean event’s testGetValue() have the event metric’s category and name, you never need to check them. They are always correct: e.g. Assert.ok(Glean.myCategory.myEvent.testGetValue()?.every(record => record.category = 'my.category' && record.name == 'my_event'), "always true, so don't bother checking.");

• For C++ tests you no longer need fake JSContexts. Just use TestGetValue().unwrap().value().

  • If you felt like you had to add script-visible APIs to test C++ instrumentation in JS, you may be able to remove them now and test instrumentation directly.

• You may no longer need a PingServer to test that pings are submitted. Instead use GleanPings.myPing.testSubmission() (JS) or mozilla::glean_pings::MyPing.TestSubmission() (C++) to ensure that the ping is submitted, and to use testGetValue() to check that the data is correct at the time it is submitted.

• Any use of waitForCondition() or other busy loops to wait for Legacy Telemetry IPC can be replaced with await Services.fog.testFlushAllChildren();.

• If your test relied on clearing individual Histograms, it will need to be rewritten to instead clear all data via Services.fog.testResetFOG().