Skip to content
Switch branches/tags
Go to file
Cannot retrieve contributors at this time

Secure-Proxy telemetry events

Last Updated: Dec 03, 2019

This is the metrics collection plan for Secure-Proxy. It documents all events currently collected through telemetry, as well those planned for collection but not currently implemented. It will be updated periodically to reflect all new and planned data collection.


Data collection is done solely for the purpose of product development, improvement and maintenance.

The data collection outlined here is geared toward answering the following questions (see List of Implemented Events):

  • Is the current user-interface good enough?
    • Is the panel opened?
    • Is the settings page visible enough?
    • What's the most important URL in the settings page?
    • Do the users manage their accounts through the settings page?
    • What's the most common way to disable/enable the proxy?
  • How often we have proxy errors. In particular we care about these errors:
    • The extension is sending an invalid token
    • The proxy endpoint reports an user abuse
    • The proxy seems to be down
  • How often we have authentication errors. In particular we care about:
    • How often the user starts the authentication flow
    • How often the authentication flow succeeds and how often it fails.
  • What is the amount of bandwidth consumed when the proxy is in use?


To record Telemetry we will be making use of the public JavaScript API that allows recording and sending of events.

Once telemetry is logged on the measurements should appear in about:telemetry. From there they will be submitted in the "event" ping payload under and available through the usual services (STMO), as well as amplitude (eventually).

Event Registration and Recording

The events that we will record will conform to the structure expected by the telemetry pipeline. When the events are logged in telemetry they will be a list of:

[timestamp, category, method, object, value, extra]

The API takes care of the timestamp for us. We just need to define category, method and object. value is optional and it's used only for some objects.

Events are defined by registering them using a call to browser.telemetry.registerEvents(category, eventData).

Here's a breakdown of how a to register a typical event:

browser.telemetry.registerEvents("eventcategory", {
    "eventName": {
        methods: ["click", ... ], // types of events that can occur
        objects: ["aButton", ... ], // objects event can occur on
        extra: {"key": "value", ... } // key-value pairs (strings)

Once an event is registered, we can record it with: (*)

browser.telemetry.recordEvent(category, method, object, value, extra)

Note: The semantics of value is contingent on the event being recorded, see list below.

List of Planned Events

All events are currently implemented under the category: secure.proxy. If not specified differently, value is passed as null. If not specified differently, extra is an object containing the extension version number.

The methods are:

  1. general fires when the extension detects a generic operation/error. objects:
    1. otherProxyInUse: another proxy setting has been detected.
    2. settingsShown: the settings view is shown.
    3. loadingError: the loading of the panel fails (this is based on a timer)
    4. install: the extension has been installed. value: the version number.
    5. update: the extension has been updated. value: the version number.
    6. panelShown: the proxy panel has been opened.
  2. fxa fires when there are authentication events. objects:
    1. authStarted: the user has started the authentication flow. (user-interaction)
    2. authCompleted: the user has completed the authentication flow.
    3. authFailed: the authentication flow has terminated with an error.
    4. authFailedByGeo: the authentication flow has terminated with an geo-restriction error.
  3. networking fires when there is a proxy network error. objects:
    1. 407: a 407 error code has been received. This error is received when the proxy receives an invalid/expired token.
    2. 429: the proxy returns 429 when the user is abusing of the service. The concept of "abuse" has not been defined yet.
    3. 502: the proxy returns 502. We want to track this error.
    4. connecting: the proxy is unreachable during the connecting phase.
    5. proxyDown: the proxy seems unreachable.
  4. state fires when the proxy state changes
    1. proxyEnabled: the proxy is enabled by user-interaction. value: only stateButton for now. extra: version, the extension version. (user-interaction)
    2. proxyDisabled: the proxy is disabled by user-interaction. value: only stateButton for now. extra: version, the extension version. (user-interaction)
  5. settings_url_clicks fires when the user interacts with the settings view. objects:
    1. manageAccount: the user clicks on the manage account URL. (user-interaction)
    2. contactUs: the user clicks on the contact us URL. (user-interaction)
    3. helpAndSupport: the user clicks on the help & support URL. (user-interaction)
    4. cloudflare: the user clicks on the Cloudflare URL. (user-interaction)
    5. privacyPolicy: the user clicks on privacy & policy URL. (user-interaction)
    6. termsAndConditions: the user clicks on terms & conditions URL. (user-interaction)
    7. giveUsFeedback: the user clicks on give-us-a-feedback URL (user-interaction)
  6. upsell_clicks fires when the user clicks on one of the upsell entrypoints. objects:
    1. paymentRequired: payment required page. (user-interaction)

scalar Registration and Recording

About how to register scalars, see

List of Planned Scalars

All scalars are currently implemented under the category: secure.proxy.

The scalars are:

  1. bandwidth contains the amount of kbytes sent and received when the proxy is in use.


Docs for the Mozilla privileged JS API that allows us to log events thru an add-on:

Telemetry Public JS API