bug 1406394 - Small correctness/readability fixes in Telemetry docs r=Dexter
authorChris H-C <chutten@mozilla.com>
Thu, 09 Nov 2017 09:37:54 -0500
changeset 436107 b3883358e0182cd158341f62e87f31c3b69f3c5d
parent 436106 a279f3cd1b8b581d886dff12739ef1f61ec0f023
child 436108 a736899d6d3186dacfdd4867e0484ac855486361
push id117
push userfmarier@mozilla.com
push dateTue, 28 Nov 2017 20:17:16 +0000
reviewersDexter
bugs1406394
milestone59.0a1
bug 1406394 - Small correctness/readability fixes in Telemetry docs r=Dexter MozReview-Commit-ID: BXu9oXqVgKQ
toolkit/components/telemetry/docs/collection/custom-pings.rst
toolkit/components/telemetry/docs/collection/events.rst
toolkit/components/telemetry/docs/collection/histograms.rst
toolkit/components/telemetry/docs/collection/measuring-time.rst
toolkit/components/telemetry/docs/collection/use-counters.rst
toolkit/components/telemetry/docs/concepts/crashes.rst
toolkit/components/telemetry/docs/concepts/pings.rst
toolkit/components/telemetry/docs/concepts/sessions.rst
toolkit/components/telemetry/docs/data/anonymous-ping.rst
toolkit/components/telemetry/docs/data/crash-ping.rst
toolkit/components/telemetry/docs/data/deletion-ping.rst
toolkit/components/telemetry/docs/data/first-shutdown-ping.rst
toolkit/components/telemetry/docs/data/health-ping.rst
toolkit/components/telemetry/docs/data/main-ping.rst
toolkit/components/telemetry/docs/data/modules-ping.rst
toolkit/components/telemetry/docs/data/sync-ping.rst
toolkit/components/telemetry/docs/data/uitour-ping.rst
toolkit/components/telemetry/docs/internals/pingsender.rst
--- a/toolkit/components/telemetry/docs/collection/custom-pings.rst
+++ b/toolkit/components/telemetry/docs/collection/custom-pings.rst
@@ -12,17 +12,17 @@ Custom pings can be submitted from JavaS
 - ``payload`` - the actual payload data for the ping, has to be a JSON style object.
 - ``options`` - optional, an object containing additional options:
    - ``addClientId``- whether to add the client id to the ping, defaults to ``false``
    - ``addEnvironment`` - whether to add the environment data to the ping, defaults to ``false``
    - ``overrideEnvironment`` - a JSON style object that overrides the environment data
 
 ``TelemetryController`` will assemble a ping with the passed payload and the specified options.
 That ping will be archived locally for use with Shield and inspection in ``about:telemetry``.
-If the preferences allow upload of Telemetry pings, the ping will be uploaded at the next opportunity (this is subject to throttling, retry-on-failure, etc.).
+If preferences allow the upload of Telemetry pings, the ping will be uploaded at the next opportunity (this is subject to throttling, retry-on-failure, etc.).
 
 .. important::
 
     Every new data collection in Firefox needs a `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection#Requesting_Approval>`_ from a data collection peer. Just set the feedback? flag for one of the data peers. We try to reply within a business day.
 
 Submission constraints
 ----------------------
 
--- a/toolkit/components/telemetry/docs/collection/events.rst
+++ b/toolkit/components/telemetry/docs/collection/events.rst
@@ -1,16 +1,16 @@
 .. _eventtelemetry:
 
 ======
 Events
 ======
 
 Across the different Firefox initiatives, there is a common need for a mechanism for recording, storing, sending & analysing application usage in an event-oriented format.
-*Event Telemetry* specifies a common events dataformat, which allows for broader, shared usage of data processing tools.
+*Event Telemetry* specifies a common events data format, which allows for broader, shared usage of data processing tools.
 
 For events recorded into Firefox Telemetry we also provide an API that opaquely handles storage and submission to our servers.
 
 .. important::
 
     Every new data collection in Firefox needs a `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection#Requesting_Approval>`_ from a data collection peer. Just set the feedback? flag for one of the data peers. We try to reply within a business day.
 
 Serialization format
--- a/toolkit/components/telemetry/docs/collection/histograms.rst
+++ b/toolkit/components/telemetry/docs/collection/histograms.rst
@@ -1,13 +1,13 @@
 ==========
 Histograms
 ==========
 
-If a user has opted into submitting performance data to Mozilla, the Telemetry system will collect various measures of Firefox performance, hardware, usage and customizations and submit it to Mozilla. The Telemetry data collected by a single client can be examined from the integrated ``about:telemetry`` browser page, while the aggregated reports across entire user populations are publicly available at `telemetry.mozilla.org <https://telemetry.mozilla.org>`_.
+In Firefox, the Telemetry system collects various measures of Firefox performance, hardware, usage and customizations and submits it to Mozilla. The Telemetry data collected by a single client can be examined from the integrated ``about:telemetry`` browser page, while the aggregated reports across entire user populations are publicly available at `telemetry.mozilla.org <https://telemetry.mozilla.org>`_.
 
 .. important::
 
     Every new data collection in Firefox needs a `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection#Requesting_Approval>`_ from a data collection peer. Just set the feedback? flag for one of the data peers. We try to reply within a business day.
 
 The following sections explain how to add a new measurement to Telemetry.
 
 Overview
@@ -125,17 +125,17 @@ The possible fields in a histogram decla
 
 ``record_in_processes``
 -----------------------
 Required. This field is a list of processes this histogram can be recorded in. Currently-supported values are:
 
 - ``main``
 - ``content``
 - ``gpu``
-- ``all_child`` (record in all child processes)
+- ``all_childs`` (record in all child processes)
 - ``all`` (record in all processes)
 
 ``alert_emails``
 ----------------
 Required. This field is a list of e-mail addresses that should be notified when the distribution of the histogram changes significantly from one build-id to the other. This can be useful to detect regressions. Note that all alerts will be sent automatically to mozilla.dev.telemetry-alerts.
 
 ``expires_in_version``
 ----------------------
@@ -190,42 +190,44 @@ Optional. This field inserts an #ifdef d
 ----------------------------
 Optional. This is one of:
 
 * ``"opt-in"``: (default value) This histogram is submitted by default on pre-release channels; on the release channel only if the user opted into additional data collection
 * ``"opt-out"``: this histogram is submitted by default on release and pre-release channels, unless the user opted out.
 
 .. warning::
 
-    Because they are collected by default, opt-out probes need to meet a higher "user benefit" threshold than opt-in probes.
+    Because they are collected by default, opt-out probes need to meet a higher "user benefit" threshold than opt-in probes during data collection review.
 
 
     **Every** new data collection in Firefox needs a `data collection review <https://wiki.mozilla.org/Firefox/Data_Collection#Requesting_Approval>`_ from a data collection peer. Just set the feedback? flag for one of the data peers.
 
 Changing a histogram
 ====================
-Changing histogram declarations after the histogram has been released is tricky. The current recommended procedure is to change the name of the histogram.
+Changing histogram declarations after the histogram has been released is tricky. Many tools (like `the aggregator <https://github.com/mozilla/python_mozaggregator>`_) assume histograms don't change. The current recommended procedure is to change the name of the histogram.
 
 * When changing existing histograms, the recommended pattern is to use a versioned name (``PROBE``, ``PROBE_2``, ``PROBE_3``, ...).
 * For enum histograms, it's recommended to set "n_buckets" to a slightly larger value than needed since new elements may be added to the enum in the future.
 
+The one exception is categorical histograms which can only be changed by adding labels, and only until it reaches 50 labels.
+
 Adding a JavaScript Probe
 =========================
 
 A Telemetry probe is the code that measures and stores values in a histogram. Probes in privileged JavaScript code can make use of the `nsITelemetry <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/nsITelemetry.idl>`_ interface to get references to histogram objects. A new value is recorded in the histogram by calling ``add`` on the histogram object:
 
 .. code-block:: js
 
   let histogram = Services.telemetry.getHistogramById("PLACES_AUTOCOMPLETE_1ST_RESULT_TIME_MS");
   histogram.add(measuredDuration);
 
   let keyed = Services.telemetry.getKeyedHistogramById("TAG_SEEN_COUNTS");
   keyed.add("blink");
 
-Note that ``nsITelemetry.getHistogramById()`` will throw an ``NS_ERROR_ILLEGAL_VALUE`` JavaScript exception if it is called with an invalid histogram ID. The ``add()`` function will not throw if it fails, instead it prints an error in the browser console.
+Note that ``nsITelemetry.getHistogramById()`` will throw an ``NS_ERROR_FAILURE`` JavaScript exception if it is called with an invalid histogram ID. The ``add()`` function will not throw if it fails, instead it prints an error in the browser console.
 
 .. warning::
 
   Adding a new Telemetry probe is not possible with Artifact builds. A full build is needed.
 
 For histograms measuring time, `TelemetryStopwatch <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/TelemetryStopwatch.jsm>`_ can be used to avoid working with Dates manually:
 
 .. code-block:: js
--- a/toolkit/components/telemetry/docs/collection/measuring-time.rst
+++ b/toolkit/components/telemetry/docs/collection/measuring-time.rst
@@ -1,14 +1,14 @@
 ======================
 Measuring elapsed time
 ======================
 
 To make it easier to measure how long operations take, we have helpers for both JavaScript and C++.
-These helpers record the elapsed time into histograms, so you have to create suitable histograms for them first.
+These helpers record the elapsed time into histograms, so you have to create suitable :doc:`histograms` for them first.
 
 From JavaScript
 ===============
 JavaScript can measure elapsed time using `TelemetryStopwatch.jsm <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/TelemetryStopwatch.jsm>`_.
 
 ``TelemetryStopwatch`` is a helper that simplifies recording elapsed time (in milliseconds) into histograms (plain or keyed).
 
 API:
--- a/toolkit/components/telemetry/docs/collection/use-counters.rst
+++ b/toolkit/components/telemetry/docs/collection/use-counters.rst
@@ -1,15 +1,15 @@
 ============
 Use Counters
 ============
 
 Use counters are used to report Telemetry statistics on whether individual documents
 use a given WebIDL method or attribute (getters and setters are reported separately), CSS
-property and deprecated DOM operations.  Custom use counters can also be
+property, or deprecated DOM operation.  Custom use counters can also be
 defined to test frequency of things that don't fall into one of those
 categories.
 
 The API
 =======
 The process to add a new use counter is different depending on the type feature that needs
 to be measured. In general, for each defined use counter, two separate boolean histograms are generated:
 
@@ -73,9 +73,8 @@ The definition files are processed twice
     The histograms that are generated out of use counters are set to *never* expire and are *opt-in*.
 
 gen-usecounters.py
 ------------------
 This script is called by the build system to generate:
 
 - the ``PropertyUseCounterMap.inc`` C++ header for the CSS properties;
 - the ``UseCounterList.h`` header for the WebIDL, out of the definition files.
-
--- a/toolkit/components/telemetry/docs/concepts/crashes.rst
+++ b/toolkit/components/telemetry/docs/concepts/crashes.rst
@@ -13,11 +13,13 @@ If we have a crash dump for that crash, 
 The ``aborted-session`` information is first written to disk 60 seconds after startup, any earlier crashes will not trigger an ``aborted-session`` ping.
 Also, the ``aborted-session`` is updated at least every 5 minutes, so it may lag behind the last session state.
 
 Crashes during startup should be recorded in the next sessions main ping in the ``STARTUP_CRASH_DETECTED`` histogram.
 
 Child process crashes
 =====================
 
-If a Firefox plugin, content or gmplugin process dies unexpectedly, this is recorded in the main pings ``SUBPROCESS_ABNORMAL_ABORT`` keyed histogram.
+If a Firefox plugin, content, gmplugin, or any other type of child process dies unexpectedly, this is recorded in the main ping's ``SUBPROCESS_ABNORMAL_ABORT`` keyed histogram.
 
 If we catch a crash report for this, then additionally the ``SUBPROCESS_CRASHES_WITH_DUMP`` keyed histogram is incremented.
+
+Some processes also generate :doc:`crash pings <../data/crash-ping>` when they crash and generate a crash dump. See `bug 1352496 <https://bugzilla.mozilla.org/show_bug.cgi?id=1352496>`_ for an example of how to allow crash pings for new process types.
--- a/toolkit/components/telemetry/docs/concepts/pings.rst
+++ b/toolkit/components/telemetry/docs/concepts/pings.rst
@@ -1,32 +1,29 @@
 .. _telemetry_pings:
 
 =====================
 Telemetry pings
 =====================
 
 A *Telemetry ping* is the data that we send to Mozilla's Telemetry servers.
 
-That data is stored as a JSON object client-side and contains common information to all pings and a payload specific to a certain *ping types*.
-
-The top-level structure is defined by the :doc:`common ping format <../data/common-ping>` format.
-It contains:
+The top-level structure is defined by the :doc:`common ping format <../data/common-ping>`. This is a JSON object which contains:
 
 * some basic information shared between different ping types
 * the :doc:`environment data <../data/environment>` (optional)
 * the data specific to the *ping type*, the *payload*.
 
 Ping types
 ==========
 
 We send Telemetry with different ping types. The :doc:`main <../data/main-ping>` ping is the ping that contains the bulk of the Telemetry measurements for Firefox. For more specific use-cases, we send other ping types.
 
 Pings sent from code that ships with Firefox are listed in the :doc:`data documentation <../data/index>`.
 
 Important examples are:
 
-* :doc:`main <../data/main-ping>` - contains the information collected by Telemetry (Histograms, hang stacks, ...)
+* :doc:`main <../data/main-ping>` - contains the information collected by Telemetry (Histograms, Scalars, ...)
 * :doc:`saved-session <../data/main-ping>` - has the same format as a main ping, but it contains the *"classic"* Telemetry payload with measurements covering the whole browser session. This is only a separate type to make storage of saved-session easier server-side. This is temporary and will be removed soon.
-* :doc:`crash <../data/crash-ping>` - a ping that is captured and sent after Firefox crashes.
+* :doc:`crash <../data/crash-ping>` - a ping that is captured and sent after a Firefox process crashes.
 * :doc:`new-profile <../data/new-profile-ping>` - sent on the first run of a new profile.
 * :doc:`update <../data/update-ping>` - sent right after an update is downloaded.
 * :doc:`deletion <../data/deletion-ping>` - sent when FHR upload is disabled, requesting deletion of the data associated with this user.
--- a/toolkit/components/telemetry/docs/concepts/sessions.rst
+++ b/toolkit/components/telemetry/docs/concepts/sessions.rst
@@ -1,14 +1,14 @@
 ========
 Sessions
 ========
 
 A *session* is the time from when Firefox starts until it shuts down.
-A session can be very long-running. E.g. for Mac users that are used to always put their laptops into sleep-mode, Firefox may run for weeks.
+A session can be very long-running. E.g. for users that always put their computers into sleep-mode, Firefox may run for weeks.
 We slice the sessions into smaller logical units called *subsessions*.
 
 Subsessions
 ===========
 
 The first subsession starts when the browser starts. After that, we split the subsession for different reasons:
 
 * ``daily``, when crossing local midnight. This keeps latency acceptable by triggering a ping at least daily for most active users.
--- a/toolkit/components/telemetry/docs/data/anonymous-ping.rst
+++ b/toolkit/components/telemetry/docs/data/anonymous-ping.rst
@@ -1,11 +1,15 @@
 
 "anonymous" ping
-============
+================
+
+.. note::
+
+    This ping is no longer sent by Firefox or Fennec.
 
 This ping is only for product survey purpose and will not track/associate client ID. It's used
 to evaluate custom tab usage and see which app is using our custom tab.
 
 Submission interval & triggers
 Since this ping is used to measure the feature usage, it should be sent each time the client app uses our custom tab.
 
 Dataset:
@@ -56,9 +60,9 @@ client
 It could be ``com.example.app``, which is the identifier of the app.
 
 Version history
 ---------------
 * v1: initial version - Will be shipped in `Fennec 55 <https://bugzilla.mozilla.org/show_bug.cgi?id=1329157>`_.
 
 Notes
 ~~~~~
-There's no option in this custom ping since we don't collect clientId nor environment data.
\ No newline at end of file
+There's no option in this custom ping since we don't collect clientId nor environment data.
--- a/toolkit/components/telemetry/docs/data/crash-ping.rst
+++ b/toolkit/components/telemetry/docs/data/crash-ping.rst
@@ -7,18 +7,17 @@ process crashes, whether or not the cras
 crash-stats.mozilla.org. It includes non-identifying metadata about the crash.
 
 This ping is sent either by the ```CrashManager``` or by the crash reporter
 client. The ```CrashManager``` is responsible for sending crash pings for the
 child processes crashes, which are sent right after the crash is detected,
 as well as for main process crashes, which are sent after Firefox restarts
 successfully. The crash reporter client sends crash pings only for main process
 crashes whether or not the user also reports the crash. The crash reporter
-client will not send the crash ping if telemetry has been disabled in Firefox
-though.
+client will not send the crash ping if telemetry has been disabled in Firefox.
 
 The environment block that is sent with this ping varies: if Firefox was running long enough to record the environment block before the crash, then the environment at the time of the crash will be recorded and ``hasCrashEnvironment`` will be true. If Firefox crashed before the environment was recorded, ``hasCrashEnvironment`` will be false and the recorded environment will be the environment at time of submission.
 
 The client ID is submitted with this ping.
 
 Structure:
 
 .. code-block:: js
@@ -72,17 +71,17 @@ Structure:
         },
         hasCrashEnvironment: bool
       }
     }
 
 .. note::
 
   For "crash" pings generated by the crashreporter we are deliberately truncating the ``creationDate``
-  to hours. See bug 1345108 for context.
+  to hours. See `bug 1345108 <https://bugzilla.mozilla.org/show_bug.cgi?id=1345108>`_ for context.
 
 Process Types
 -------------
 
 The ``processType`` field contains the type of process that crashed. There are
 currently multiple process types defined in ``nsICrashService`` but crash pings
 are sent only for the ones below:
 
--- a/toolkit/components/telemetry/docs/data/deletion-ping.rst
+++ b/toolkit/components/telemetry/docs/data/deletion-ping.rst
@@ -11,9 +11,9 @@ Structure:
 .. code-block:: js
 
     {
       version: 4,
       type: "deletion",
       ... common ping data
       clientId: <UUID>,
       payload: { }
-    }
\ No newline at end of file
+    }
--- a/toolkit/components/telemetry/docs/data/first-shutdown-ping.rst
+++ b/toolkit/components/telemetry/docs/data/first-shutdown-ping.rst
@@ -1,10 +1,11 @@
 
 "first-shutdown" ping
-==================
+=====================
 
 This ping is a duplicate of the main-ping sent on first shutdown. Enabling pingsender
 for first sessions will impact existing engagment metrics. The ``first-shutdown`` ping enables a
 more accurate view of users that churn after the first session. This ping exists as a
-stopgap until existing metrics are re-evaluated for use first session ``main-pings``.
+stopgap until existing metrics are re-evaluated, allowing us to use the first session
+``main-pings`` directly.
 
 See :doc:`main-ping` for details about this payload.
--- a/toolkit/components/telemetry/docs/data/health-ping.rst
+++ b/toolkit/components/telemetry/docs/data/health-ping.rst
@@ -35,40 +35,40 @@ The client id is submitted with this pin
       }
     }
 
 Send behavior
 -------------
 
 ``TelemetryHealthPing.jsm`` tracks several problems:
 
-* The size of other assembled ping exceed the ping limit.
-* There was a failure while sending other ping.
+* The size of other assembled pings exceeds the ping limit.
+* Failures while sending other pings.
 
-After recording the data, ping will be sent:
+After recording the data, a health ping will be sent:
 
 * immediately, with the reason ``immediate`` , if it is first ping in the session or it passed at least one hour from the previous submission.
 * after 1 hour minus the time passed from previous submission, with the reason ``delayed`` , if less than an hour passed from the previous submission.
 * on shutdown, with the reason ``shutdown`` using :doc:`../internals/pingsender`, if recorded data is not empty.
 
 Field details
 -------------
 
 reason
 ~~~~~~
-The ``reason`` field contains the information about when "health" ping was submitted. Now it supports three types:
+The ``reason`` field contains the information about why the "health" ping was submitted. It presently supports three reasons:
 
 * immediate: The health ping was submitted immediately after recording a failure.
 * delayed: The health ping was submitted after a delay.
 * shutdown: The health ping was submitted on shutdown.
 
 pingDiscardedForSize
 ~~~~~~~~~~~~~~~~~~~~
-The ``pingDiscardedForSize`` field contains the information about top ten pings, whose size exceeded the
-ping size limit (1 mb). This field lists the number of discarded pings per ping type.
+The ``pingDiscardedForSize`` field contains the information about the top ten pings whose size exceeded the
+ping size limit (1 MB). This field lists the number of discarded pings per ping type.
 
 The ping type "<unknown>" is used to indicate that a pending pings size exceeded the limit. This is because we don't have the pending pings type available cheaply at the moment.
 
 This field is optional.
 
 sendFailure
 ~~~~~~~~~~~
 The ``sendFailure`` field contains the information about pings, which had failures on sending.
--- a/toolkit/components/telemetry/docs/data/main-ping.rst
+++ b/toolkit/components/telemetry/docs/data/main-ping.rst
@@ -1,19 +1,19 @@
 
 "main" ping
 ===========
 
 .. toctree::
    :maxdepth: 2
 
 This is the "main" Telemetry ping type, whose payload contains most of the measurements that are used to track the performance and health of Firefox in the wild.
-It includes the histograms and other performance and diagnostic data.
+It includes histograms and other performance and diagnostic data.
 
-This ping is triggered by different scenarios, which is documented by the ``reason`` field:
+This ping may be triggered for one of many reasons documented by the ``reason`` field:
 
 * ``aborted-session`` - this ping is regularly saved to disk (every 5 minutes), overwriting itself, and deleted at shutdown. If a previous aborted session ping is found at startup, it gets sent to the server. The first aborted-session ping is generated as soon as Telemetry starts
 * ``environment-change`` - the :doc:`environment` changed, so the session measurements got reset and a new subsession starts
 * ``shutdown`` - triggered when the browser session ends. For the first browsing session, this ping is saved to disk and sent on the next browser restart. From the second browsing session on, this ping is sent immediately on shutdown using the :doc:`../internals/pingsender`, unless the OS is shutting down
 * ``daily`` - a session split triggered in 24h hour intervals at local midnight. If an ``environment-change`` ping is generated by the time it should be sent, the daily ping is rescheduled for the next midnight
 * ``saved-session`` - the *"classic"* Telemetry payload with measurements covering the whole browser session (only submitted for a transition period)
 
 Most reasons lead to a session split, initiating a new *subsession*. We reset important measurements for those subsessions.
@@ -236,27 +236,27 @@ This measure might be useful to give a t
 Note that in ``main`` pings, this measure is reset on subsession splits, while in ``saved-session`` pings it covers the whole browser session.
 
 pingsOverdue
 ~~~~~~~~~~~~
 Integer count of pending pings that are overdue.
 
 histograms
 ----------
-This section contains the histograms that are valid for the current platform. ``Flag`` and ``count`` histograms are always created and submitted, with their default value being respectively ``false`` and ``0``. Other histogram types (see :ref:`choosing-histogram-type`) are not created nor submitted if no data was added to them. The type and format of the reported histograms is described by the ``Histograms.json`` file. Its most recent version is available `here <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Histograms.json>`_. The ``info.revision`` field indicates the revision of the file that describes the reported histograms.
+This section contains the histograms that are valid for the current platform. ``Flag`` histograms are always created and submitted with a default value of ``false`` if a value of ``true`` is not recorded during the time period. Other histogram types (see :ref:`choosing-histogram-type`) are not created nor submitted if no data was added to them. The type and format of the reported histograms is described by the ``Histograms.json`` file. Its most recent version is available `here <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Histograms.json>`_. The ``info.revision`` field indicates the revision of the file that describes the reported histograms.
 
 keyedHistograms
 ---------------
 This section contains the keyed histograms available for the current platform.
 
 As of Firefox 48, this section does not contain empty keyed histograms anymore.
 
 threadHangStats
 ---------------
-As of Firefox 57 this section is no longer present, and has been replaced with the 'bhr' ping.
+As of Firefox 57 this section is no longer present, and has been replaced with the :doc:`bhr ping <backgroundhangmonitor-ping>`.
 
 Contains the statistics about the hangs in main and background threads. Note that hangs in this section capture the `C++ pseudostack <https://developer.mozilla.org/en-US/docs/Mozilla/Performance/Profiling_with_the_Built-in_Profiler#Native_stack_vs._Pseudo_stack>`_ and an incomplete JS stack, which is not 100% precise. For particularly egregious hangs, and on nightly, an unsymbolicated native stack is also captured. The amount of time that is considered "egregious" is different from thread to thread, and is set when the BackgroundHangMonitor is constructed for that thread. In general though, hangs from 5 - 10 seconds are generally considered egregious. Shorter hangs (1 - 2s) are considered egregious for other threads (the compositor thread, and the hang monitor that is only enabled during tab switch).
 
 To avoid submitting overly large payloads, some limits are applied:
 
 * Identical, adjacent "(chrome script)" or "(content script)" stack entries are collapsed together. If a stack is reduced, the "(reduced stack)" frame marker is added as the oldest frame.
 * The depth of the reported pseudostacks is limited to 11 entries. This value represents the 99.9th percentile of the thread hangs stack depths reported by Telemetry.
 * The native stacks are limited to a depth of 25 stack frames.
--- a/toolkit/components/telemetry/docs/data/modules-ping.rst
+++ b/toolkit/components/telemetry/docs/data/modules-ping.rst
@@ -1,15 +1,15 @@
 
 "modules" ping
-============
+==============
 
 This ping is sent once a week and includes the modules loaded in the Firefox process.
 
-The client ID and environment is submitted with this ping.
+The client ID and environment are submitted with this ping.
 
 Structure:
 
 .. code-block:: js
 
     {
       type: "modules",
       ... common ping data
--- a/toolkit/components/telemetry/docs/data/sync-ping.rst
+++ b/toolkit/components/telemetry/docs/data/sync-ping.rst
@@ -1,15 +1,15 @@
 
 "sync" ping
 ===========
 
-This is an aggregated format that contains information about each sync that occurred during a timeframe. It is submitted every 12 hours, and on browser shutdown, but only if the syncs property would not be empty. The ping does not contain the enviroment block, nor the clientId.
+This is an aggregated format that contains information about each sync that occurred during a timeframe. It is submitted every 12 hours, and on browser shutdown, but only if the ``syncs`` property would not be empty. The ping does not contain the enviroment block, nor the clientId.
 
-Each item in the syncs property is generated after a sync is completed, for both successful and failed syncs, and contains measurements pertaining to sync performance and error information.
+Each item in the ``syncs`` property is generated after a sync is completed, for both successful and failed syncs, and contains measurements pertaining to sync performance and error information.
 
 A JSON-schema document describing the exact format of the ping's payload property can be found at `services/sync/tests/unit/sync\_ping\_schema.json <https://dxr.mozilla.org/mozilla-central/source/services/sync/tests/unit/sync_ping_schema.json>`_.
 
 Structure:
 
 .. code-block:: js
 
     {
--- a/toolkit/components/telemetry/docs/data/uitour-ping.rst
+++ b/toolkit/components/telemetry/docs/data/uitour-ping.rst
@@ -1,13 +1,13 @@
 
 "uitour-tag" ping
 =================
 
-This ping is submitted via the UITour setTreatmentTag API. It may be used by
+This ping is submitted via the UITour ``setTreatmentTag`` API. It may be used by
 the tour to record what settings were made by a user or to track the result of
 A/B experiments.
 
 The client ID is submitted with this ping.
 
 Structure:
 
 .. code-block:: js
--- a/toolkit/components/telemetry/docs/internals/pingsender.rst
+++ b/toolkit/components/telemetry/docs/internals/pingsender.rst
@@ -27,10 +27,10 @@ additional headers:
   system proxy configuration.
 
 In non-debug mode the ping sender doesn't print anything, not even on error,
 this is done deliberately to prevent startling the user on architectures such
 as Windows that would open a separate console window just to display the
 program output. If you need runtime information to be printed out compile the
 ping sender with debugging enabled.
 
-The pingsender is not supported on Firefox for Android at the moment
+The pingsender is not supported on Firefox for Android
 (see `bug 1335917 <https://bugzilla.mozilla.org/show_bug.cgi?id=1335917>`_)