Architecture

healthreporter.sys.mjs contains the main interface for FHR, the HealthReporter type. An instance of this is created by the data_reporting_service.

providers.sys.mjs contains numerous Metrics.Provider and Metrics.Measurement used for collecting application metrics. If you are looking for the FHR probes, this is where they are.

Storage

Firefox Health Report stores data in 3 locations:

• Metrics measurements and provider state is stored in a SQLite database (via Metrics.Storage).

• Service state (such as the IDs of documents uploaded) is stored in a JSON file on disk (via OS.File).

• Lesser state and run-time options are stored in preferences.

Preferences

Preferences controlling behavior of Firefox Health Report live in the datareporting.healthreport.* branch.

Service and Data Control

The follow preferences control behavior of the service and data upload.

service.enabled

Controls whether the entire health report service runs. The overall service performs data collection, storing, and submission.

This is the primary kill switch for Firefox Health Report outside of the build system variable. i.e. if you are using an official Firefox build and wish to disable FHR, this is what you should set to false to prevent FHR from not only submitting but also collecting data.

uploadEnabled

Whether uploading of data is enabled. This is the preference the checkbox in the preferences UI reflects. If this is disabled, FHR still collects data - it just doesn’t upload it.

service.loadDelayMsec

How long (in milliseconds) after initial application start should FHR wait before initializing.

FHR may initialize sooner than this if the FHR service is requested. This will happen if e.g. the user goes to about:healthreport.

service.loadDelayFirstRunMsec

How long (in milliseconds) FHR should wait to initialize on first application run.

FHR waits longer than normal to initialize on first application run because first-time initialization can use a lot of I/O to initialize the SQLite database and this I/O should not interfere with the first-run user experience.

documentServerURI

The URI of a Bagheera server that FHR should interface with for submitting documents.

You typically do not need to change this.

documentServerNamespace

The namespace on the document server FHR should upload documents to.

You typically do not need to change this.

infoURL

The URL of a page containing more info about FHR, it’s privacy policy, etc.

about.reportUrl

The URL to load in about:healthreport.

about.reportUrlUnified

The URL to load in about:healthreport. This is used instead of reportUrl for UnifiedTelemetry when it is not opt-in.

service.providerCategories

A comma-delimited list of category manager categories that contain registered Metrics.Provider records. Read below for how provider registration works.

If the entire service is disabled, you lose data collection. This means that local data analysis won’t be available because there is no data to analyze! Keep in mind that Firefox Health Report can be useful even if it’s not submitting data to remote servers!

Logging

The following preferences allow you to control the logging behavior of Firefox Health Report.

logging.consoleEnabled

Whether to write log messages to the web console. This is true by default.

logging.consoleLevel

The minimum log level FHR messages must have to be written to the web console. By default, only FHR warnings or errors will be written to the web console. During normal/expected operation, no messages of this type should be produced.

logging.dumpEnabled

Whether to write log messages via dump(). If true, FHR will write messages to stdout/stderr.

This is typically only enabled when developing FHR.

logging.dumpLevel

The minimum log level messages must have to be written via dump().

State

currentDaySubmissionFailureCount

How many submission failures the client has encountered while attempting to upload the most recent document.

lastDataSubmissionFailureTime

The time of the last failed document upload.

lastDataSubmissionRequestedTime

The time of the last document upload attempt.

lastDataSubmissionSuccessfulTime

The time of the last successful document upload.

nextDataSubmissionTime

The time the next data submission is scheduled for. FHR will not attempt to upload a new document before this time.

pendingDeleteRemoteData

Whether the client currently has a pending request to delete remote data. If true, the client will attempt to delete all remote data before an upload is performed.

FHR stores various state in preferences.

Registering Providers

Firefox Health Report providers are registered via the category manager. See HealthReportComponents.manifest for providers defined in this directory.

Essentially, the category manager receives the name of a JS type and the URI of a sys.mjs to import that exports this symbol. At run-time, the providers registered in the category manager are instantiated.

Providers are registered via the category manager to make registration simple and less prone to errors. Any XPCOM component can create a category manager entry. Therefore, new data providers can be added without having to touch core Firefox Health Report code. Additionally, category manager registration means providers are more likely to be registered on FHR’s terms, when it wants. If providers were registered in code at application run-time, there would be the risk of other components prematurely instantiating FHR (causing a performance hit if performed at an inopportune time) or semi-complicated code around observers or listeners. Category manager entries are only 1 line per provider and leave FHR in control: they are simple and safe.

Document Generation and Lifecycle

FHR will attempt to submit a JSON document containing data every 24 wall clock hours.

At upload time, FHR will query the database for all information from the last 180 days and assemble this data into a JSON document. We attempt to upload this JSON document with a client-generated UUID to the configured server.

Before we attempt upload, the generated UUID is stored in the JSON state file on local disk. At this point, the client assumes the document with that UUID has been successfully stored on the server.

If the client is aware of other document UUIDs that presumably exist on the server, those UUIDs are sent with the upload request so the client can request those UUIDs be deleted. This helps ensure that each client only has 1 document/UUID on the server at any one time.

Importance of Persisting UUIDs

The choices of how, where, and when document UUIDs are stored and updated are very important. One should not attempt to change things unless she has a very detailed understanding of why things are the way they are.

The client is purposefully very conservative about forgetting about generated UUIDs. In other words, once a UUID is generated, the client deliberately holds on to that UUID until it’s very confident that UUID is no longer stored on the server. The reason we do this is because orphaned documents/UUIDs on the server can lead to faulty analysis, such as over-reporting the number of Firefox installs that stop being used.

When uploading a new UUID, we update the state and save the state file to disk before an upload attempt because if the upload succeeds but the response never makes it back to the client, we want the client to know about the uploaded UUID so it can delete it later to prevent an orphan.

We maintain a list of UUIDs locally (not simply the last UUID) because multiple upload attempts could fail the same way as the previous paragraph describes and we have no way of knowing which (if any) actually succeeded. The safest approach is to assume every document produced managed to get uploaded some how.

We store the UUIDs on a file on disk and not anywhere else because we want storage to be robust. We originally stored UUIDs in preferences, which only flush to disk periodically. Writes to preferences were apparently getting lost. We switched to writing directly to files to eliminate this window.