Merge pull request #1257 from mdboom/document-metrics-and-events

docs/user/pings/index.md

@@ -15,13 +15,20 @@ There is also a [high-level overview](ping-schedules-and-timings.html) of how th
 
 ## 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](../adding-new-metrics.md)).
+Every ping has the following keys at the top-level:
 
 - 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 `metrics` section contains the submitted values for all metric types except for [events](../metrics/event.md).
+  It has keys for each of the metric types, under which is data for each metric.
+
+- The `events` section contains the events recorded in the ping.
+
+See the [payload documentation](../../dev/core/internal/payload.md) documentation for more details for each metric type in the `metrics` and `events` section.
+
 ### The `ping_info` section
 The following fields are included in the `ping_info` section, for every ping.
 Optional fields are marked accordingly.
@@ -36,6 +43,22 @@ Optional fields are marked accordingly.
 
 All the metrics surviving application restarts (e.g. `seq`, ...) are removed once the application using the Glean SDK is uninstalled.
 
+#### The `experiments` object
+
+This object (included in the [`ping_info` section](#the-ping_info-section)) contains experiment annotations keyed by the experiment `id`. Each annotation contains the experiment `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](../experiments-api.md) on how to record experiments data.
+
+```json
+{
+  "<id>": {
+    "branch": "branch-id",
+    "extra": {
+      "some-key": "a-value"
+    }
+  }
+}
+```
+
 ### The `client_info` section
 The following fields are included in the `client_info` section.
 Optional fields are marked accordingly.
@@ -60,22 +83,6 @@ All the metrics surviving application restarts (e.g. `client_id`, ...) are remov
 
 [`Build.MODEL`]: https://developer.android.com/reference/android/os/Build.html#MODEL
 
-### 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.
-See [Using the Experiments API](../experiments-api.md) on how to record experiments data.
-
-```json
-{
-  "<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.