Glean Pings

Every Glean ping is in JSON format and contains one or more of the common sections with shared information data.

If data collection is enabled, the Glean SDK provides a set of built-in pings that are assembled out of the box without any developer intervention. The following is a list of these built-in pings:

Applications can also define and send their own custom pings.

Ping sections

There are two standard metadata sections that are added to most pings, in addition to their core metrics and events content (which are described in Adding new metrics).

  • The ping_info section contains core metadata that is included in every ping.

  • The client_info section contains information that identifies the client. It is included in most pings (including all built-in pings), but may be excluded from pings where we don't want to connect client information with the other metrics in the ping.

The ping_info section

The following fields are included in the ping_info section, for every ping. Optional fields are marked accordingly.

Field nameTypeDescription
ping_typeStringThe name of the ping type (e.g. "baseline", "metrics")
seqCounterA running counter of the number of times pings of this type have been sent
experimentsObjectOptional. A dictionary of active experiments
start_timeDatetimeThe time of the start of collection of the data in the ping, in local time and with minute precision, including timezone information.
end_timeDatetimeThe time of the end of collection of the data in the ping, in local time and with minute precision, including timezone information. This is also the time this ping was generated and is likely well before ping transmission time.

All the metrics surviving application restarts (e.g. seq, ...) are removed once the application using the Glean SDK is uninstalled.

The client_info section

The following fields are included in the client_info section. Optional fields are marked accordingly.

Field nameTypeDescription
app_buildStringThe build identifier generated by the CI system (e.g. "1234/A")
app_display_versionStringThe user-visible version string (e.g. "1.0.3")
app_channelStringOptional The product-provided release channel (e.g. "beta")
architectureStringThe architecture of the device (e.g. "arm", "x86")
client_idUUIDA UUID identifying a profile and allowing user-oriented correlation of data
device_manufacturerStringThe manufacturer of the device
device_modelStringThe model name of the device
first_run_dateDatetimeThe date of the first run of the application, in local time and with day precision, including timezone information.
osStringThe name of the operating system (e.g. "linux", "Android", "ios")
os_versionStringThe user-visible version of the operating system (e.g. "1.2.3")
android_sdk_versionStringOptional. The Android specific SDK version of the software running on this hardware device (e.g. "23")
telemetry_sdk_buildStringThe version of the Glean SDK

All the metrics surviving application restarts (e.g. client_id, ...) are removed once the application using the Glean SDK is uninstalled.

The experiments object

This object (included in the ping_info section) contains experiments keyed by the experiment id. Each listed experiment contains the branch the client is enrolled in and may contain a string to string map with additional data in the extra key. Both the id and branch are truncated to 30 characters. See Using the Experiments API on how to record experiments data.

{
  "<id>": {
    "branch": "branch-id",
    "extra": {
      "some-key": "a-value"
    }
  }
}

Ping submission

The pings that the Glean SDK generates are submitted to the Mozilla servers at specific paths, in order to provide additional metadata without the need to unpack the ping payload. A typical submission URL looks like

"<server-address>/submit/<application-id>/<doc-type>/<glean-schema-version>/<ping-uuid>"

where:

  • <server-address>: the address of the server that receives the pings;
  • <application-id>: a unique application id, automatically detected by the Glean SDK; this is the value returned by Context.getPackageName();
  • <doc-type>: the name of the ping; this can be one of the pings available out of the box with the Glean SDK, or a custom ping;
  • <glean-schema-version>: the version of the Glean ping schema;
  • <ping-uuid>: a unique identifier for this ping.

Submitted headers

A pre-defined set of headers is additionally sent along with the submitted ping:

HeaderValueDescription
Content-Typeapplication/json; charset=utf-8Describes the data sent to the server
User-AgentDefaults to e.g. Glean/0.40.0 (Android), where 0.40.0 is the Glean SDK version number and Android is the platform name. It can be overriden by user through configurationDescribes the application sending the ping using the Glean SDK
Datee.g. Mon, 23 Jan 2019 10:10:10 GMT+00:00Submission date/time in GMT/UTC+0 offset
X-Client-TypeGleanCustom header to support handling of Glean pings in the legacy pipeline
X-Client-Versione.g. 0.40.0The Glean SDK version, sent as a custom header to support handling of Glean pings in the legacy pipeline

Defining background state

These docs refer to application 'background' state in several places. This specifically means when the activity is no longer visible to the user, it has entered the Stopped state, and the system invokes the onStop() callback. This may occur, for example, when a newly launched activity covers the entire screen. The system may also call onStop() when the activity has finished running, and is about to be terminated.