# glean pings

Every glean ping is in JSON format and contains one or more of the [common sections](#ping-sections)
with shared information data.

If data collection is enabled, glean 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:

- [`baseline` ping](baseline.md)
- [`events` ping](events.md)
- [`metrics` ping](metrics.md)

Applications can also define and send their own [custom pings](custom.md).

## 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 elsewhere
in [adding new metrics](../metrics/adding-new-metrics.md).

- The [`ping_info` section](#The-ping_info-section) contains core metadata that
  is included in **every** ping.
- The [`client_info` section](#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 name | Type | Description |
|---|---|---|
| `ping_type` | String | The name of the ping type (e.g. "baseline", "metrics") |
| `seq` | Counter | A running counter of the number of times pings of this type have been sent |
| `experiments` | Object | *Optional*. A dictionary of [active experiments](#the-experiments-object) |
| `start_time` | Datetime | The time of the start of collection of the data in the ping, in local time and with minute precision. See [note](#a-note-about-time-formats) |
| `end_time` | Datetime | The time of the end of collection of the data in the ping, in local time and with minute precision. This is also the time this ping was generated and is likely well before ping transmission time. See [note](#a-note-about-time-formats) |

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

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

| Field name | Type | Description |
|---|---|---|
| `app_build` | String | The build identifier generated by the CI system (e.g. "1234/A") |
| `app_display_version` | String | The user-visible version string (e.g. "1.0.3") |
| `app_channel` | String | *Optional* The product-provided release channel (e.g. "beta") |
| `architecture` | String | The architecture of the device (e.g. "arm", "x86") |
| `client_id` | UUID |  A UUID identifying a profile and allowing user-oriented correlation of data |
| `device_manufacturer` | String | The manufacturer of the device |
| `device_model` | String | The model name of the device |
| `first_run_date` | Datetime | The date of the first run of the application, in local time and with day precision. See [note](#a-note-about-time-formats) |
| `os` | String | The name of the operating system (e.g. "linux", "Android", "ios") |
| `os_version` | String | The user visible version of the operating system (e.g. "1.2.3") |
| `android_sdk_version` | String | *Optional*. The Android specific SDK version of the software running on this hardware device (e.g. "23") |
| `telemetry_sdk_build` | String | The version of the glean library |

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

### The `experiments` object 

This object (included in the [`ping_info` section](#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.

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

## Ping submission
The pings that glean 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 glean; this is the value returned by [`Context.getPackageName()`](http://developer.android.com/reference/android/content/Context.html#getPackageName());
- `<doc-type>`: the name of the ping; this can be one of the pings available out of the box with glean, 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:

| Header | Value | Description |
|--------|-------|-------------|
| `Content-Type` | `application/json; charset=utf-8` | Describes the data sent to the server |
| `User-Agent` | Defaults to e.g. `Glean/0.40.0 (Android)`, where `0.40.0` is the glean version number and `Android` is the platform name. It can be overriden by user through [configuration](https://github.com/mozilla-mobile/android-components/blob/8441728f156847a58dcb25d29254512a1801b266/components/service/glean/src/main/java/mozilla/components/service/glean/config/Configuration.kt#L23) | Describes the application sending the ping using glean |
| `Date` | e.g. `Mon, 23 Jan 2019 10:10:10 GMT+00:00` | Submission date/time in GMT/UTC+0 offset |
| `X-Client-Type` | `Glean` | Custom header to support handling of glean pings in the legacy pipeline |
| `X-Client-Version` | e.g. `0.40.0` | The glean version, sent as a custom header to support handling of glean pings in the legacy pipeline |

## A note about string length
In order to ensure that pings don't become accidentally large, most string
values are automatically truncated. The current implementation truncates based
on a maximum number of Unicode characters (defined in the API docs), since is
the most expedient implementation-wise. Other or future implementations may
perform this truncation based on the number of UTF8 bytes instead, which is
ultimately what matters for ping size.

## 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()`](https://developer.android.com/reference/android/app/Activity.html#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.

## Error reporting

Glean records the number of errors that occur when metrics are passed invalid
data or are otherwise used incorrectly. This information is reported back in
special labeled counter metrics in the `glean.error` category. Error metrics are
included in the same pings as the metric that caused the error. Additionally,
error metrics are always sent in the [`metrics` ping](metrics.md) ping.

The following categories of errors are recorded:

- `invalid_value`: The metric value was invalid or out-of-range.
- `invalid_label`: The label on a labeled metric was invalid.

For example, if you had a string metric and passed it a string that was too long:

```
MyMetrics.stringMetric.set("this_string_is_longer_than_the_limit_for_string_metrics")
```

The following error metric counter would be incremented:

```
Glean.error.invalidValue.add(1)
```

Resulting in the following keys in the ping:

```
{
  "metrics": {
    "labeled_counter": {
      "glean.error.invalid_value": {
        "my_metrics.string_metric": 1
      }
    }
  }
}
```

If you have a debug build of glean, details about the errors being recorded are
included in the logs. This detailed information is not included in glean pings.

