Mobile/Fennec/Android/UITelemetry

Overview

bug 932092 ships in Firefox 28, and allows for UI code to record telemetry events for analysis.

The concepts are:

Sessions

Sessions are essentially scopes. They are meant to give context to events; this allows events to be more simple and reusable. Sessions are usually bound to some component of the UI. They are started when the user begins interacting with the UI component and are stopped when the user leaves. They also allow you record how long a user interacts with a given UI component. A simple use-case for sessions is the bookmarks panel in about:home. We start a session when the user swipes into the panel and stop it when they leave. This bookmarks session does two things; Firstly, it gives scope to any generic event that may occur within the panel (e.g loading a URL). Secondly, it allows us to figure out how much time users are spending in the bookmarks panel.

To start a session, call Telemetry.startUISession(String sessionName). Session names should be brief, lowercase, and should describe what UI component the user is interacting with. In certain cases where the UI component is dynamic, they could include an ID, essential to identifying that component. An example of this is with dynamic home panels, we use session names of the format "homepanel:<panel_id>" to identify home panel sessions.

To stop a session call Telemetry.stopUISession(String sessionName, String reason). sessionName is the name of the session and reason is essentially the reason the session was stopped. The reason field should capture why the stopped interacting with the UI component; it should be brief, lowercase and generic so it can be reused in different places. Examples reasons are:

• "switched" - user transitioned to another UI element of equal level
• "exit" - user left for another entirely different element.

Events

Events: an occurrence at a particular time. This has a type (defaults to "event"), a timestamp, an array of active sessions (not for session events themselves), and three textual fields: action, method, extras.

• Clock: times are relative to either elapsed realtime (an arbitrary monotonically increasing clock that continues to tick when the device is asleep), or elapsed uptime (which doesn't tick when the device is in deep sleep). We default to elapsed realtime.

To define a probe, simply establish sessions:

       Telemetry.startUISession("app:foreground");
       Telemetry.stopUISession("app:foreground", "onPause");

and record events:

       Telemetry.sendUIEvent("search:setDefault", "settings:menu");

See the documentation in http://mxr.mozilla.org/mozilla-central/source/mobile/android/base/Telemetry.java for more.