metrics.md

Secure-Proxy telemetry events

Last Updated: Aug 28, 2019

• Analysis
• Collection
  • Event Registration and Recording
• List of Planned Metrics Events
• References

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.

Analysis

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 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.
• Is the webRTC-disabling message good enough?
  • Is this feature used by the user to exempt tabs?

Collection

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 processes.dynamic.events 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)
    }

For our purposes, we don't use the extra field.

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.

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. proxyEnabled: the proxy is enabled by user-interaction. value: toggleButton or stateButton.
   7. proxyDisabled: the proxy is disabled by user-interaction. value: toggleButton or stateButton.
2. fxa fires when there are authentication events. objects:
   1. authStarted: the user has started the authentication flow.
   2. authCompleted: the user has completed the authentication flow.
   3. authFailed: the authentication failed has terminated with an 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. connecting: the proxy is unreachable during the connecting phase.
   4. proxyDown: the proxy seems unreachable.
4. settings_url_clicks fires when the user interacts with the settings view. objects:
   1. manageAccount: the user clicks on the manage account URL.
   2. helpAndSupport: the user clicks on the help & support URL.
   3. cloudflare: the user clicks on the Cloudflare URL.
   4. privacyPolicy: the user clicks on privacy & policy URL.
   5. termsAndConditions: the user clicks on terms & conditions URL.
   6. giveUsFeedback: the user clicks on give-us-a-feedback URL
5. webRTC fires when the user interacts with the webRTC dialog in-content. objects:
   1. ignoreTab: the user has decided to keep the proxy on for this tab.
   2. exemptTab: the user has decided to disable the proxy for this tab.

---

References

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

Telemetry Public JS API