Recording Telemetry scalars from add-ons

The Go Faster initiative is important as it enables us to ship code faster, using special add-ons, without being strictly tied to the Firefox train schedule. As Georg Fritzsche pointed out in his article, we have two options for instrumenting these add-ons: having probe definitions ride the trains (waiting a few weeks!) or implementing and sending a new custom ping (doing some pipeline work!).

Both solutions are not very appealing when shipping code faster. But hey.. we have plan!

Our current work is focused on extending Telemetry to fill this gap. The first step consisted in enabling add-ons event recording in Firefox 56 (bug) and we recently enabled add-on scalar recording as well (bug)!

With the support for dynamic registration of scalars, add-ons can simply define the probes they want to accumulate in as soon as they start, with nsITelemetry.registerScalars(). Then they can use the JavaScript API to perform the accumulation. The Telemetry system will take care of collecting the data and adding it to the main-ping, in the the dynamic process section.

But wait, how to use them?

Let’s say we want an add-on to register a new scalar for the purpose of recording if a feature is used or not. As soon as the add-on starts, we call the registration API in the parent process providing the desired scalar definition:

With this API call, Telemetry takes care of broadcasting the definition to all the other Firefox processes so that the future accumulations work there as well. If a new process is spawned after this registration, the definition will automatically propagate there too.

Accumulating data into the newly defined scalar can be done through the usual Telemetry API:

The about:telemetry page can be used to verify that the data was correctly recorded by checking the Scalars section and choosing dynamic from the selector at the top-right of the page.

Test add-on scalars in about:telemetry

Test add-on scalars in about:telemetry

Multi-process caveats

As stated in the documentation, if an accumulation happens in a content process right after the registration and the definition still has to reach this process, it will be discarded. One way to work around the problem is to send an IPC message to the content process and start accumulating data once this message has been received.

This is not a problem in most cases, but it’s better to keep it in mind in case data needs to be recorded as soon as an add-on starts.

How to get the data?

Dynamic scalars are not currently added to any derived dataset. Custom analysis can access them in the main pings under payload/processes/dynamic/scalars.

If you want to know more about this or our next steps, reach out to us using our mailing list or on IRC ( in #telemetry.


Alessio Placitelli