1290027 - Update documentation to child histogram format changes

Status: RESOLVED FIXED

(Toolkit :: Telemetry, defect, P3)

Description

[Georg Fritzsche [:gfritzsche]]

Following up to bug 1218576, we need to update the documentation to those changes:
toolkit/components/telemetry/docs/main-ping.rst

Comment 1

[Chris H-C :chutten]

Attachment: 0001-bug-1290027-Update-main-ping-docs-for-child-telemetr.patch

Comment 2

[Chris H-C :chutten]

Due to bug 1232403 I cannot actually test the look of this. It's mostly just fiddling with content, so it ought to be fine.

Comment 3

[Georg Fritzsche [:gfritzsche]]

Comment on attachment 8784383 [details] [diff] [review]
0001-bug-1290027-Update-main-ping-docs-for-child-telemetr.patch

Review of attachment 8784383 [details] [diff] [review]:
-----------------------------------------------------------------

::: toolkit/components/telemetry/docs/data/main-ping.rst
@@ +111,4 @@
>      }
>  
> +processes.content
> +-----------------

This should use "~", not "-" (different levels of headings).

@@ +111,5 @@
>      }
>  
> +processes.content
> +-----------------
> +This section contains histograms and keyed histograms accumulated on content processes. Histograms for which Accumulate is called on a content child process have different character than parent histograms. For instance, ``GC_MS`` will be much different in ``processes.content`` as it has to content with web content, whereas the instance in ``payload.histograms`` has only to content with browser JS. Also, some histograms may be absent if Accumulate is never called from a content child process (``EVENTLOOP_UI_ACTIVITY`` is parent-process-only).

Lets in which Fx version this (probably) gets added.

We will submit scalars with "content" too.
Can we change this to a heading of "histograms & keyedHistograms"?
Then we can change this to mention that we only submit histograms for "content" now and continue with this explanation.

Nit: "content with web content"? This reads a bit confusing.
Nit: ``Accumulate()``

@@ +119,5 @@
>  This section contains the :doc:`../collection/scalars` that are valid for the current platform. Scalars are not created nor submitted if no data was added to them, and are only reported with subsession pings. Scalar data is only currently reported for the main process. Their type and format is described by the ``Scalars.yaml`` file. Its most recent version is available `here <https://dxr.mozilla.org/mozilla-central/source/toolkit/components/telemetry/Scalars.yaml>`_. The ``info.revision`` field indicates the revision of the file that describes the reported scalars.
>  
>  childPayloads
>  -------------
> +The Telemetry payloads sent by child processes, recorded on child process shutdown (event ``content-child-shutdown`` observed). They are reduced session payloads, only available with e10s. Among some other things, they don't contain histograms, keyed histograms, addon details, addon histograms, or UI Telemetry.

Lets document the old data format too and call out the bug & the Fx version this (probably) rides on.

Comment 4

[Chris H-C :chutten]

Attachment: 0001-bug-1290027-Update-main-ping-docs-for-child-telemetr.patch

Comment 5

[Georg Fritzsche [:gfritzsche]]

Comment on attachment 8785344 [details] [diff] [review]
0001-bug-1290027-Update-main-ping-docs-for-child-telemetr.patch

Review of attachment 8785344 [details] [diff] [review]:
-----------------------------------------------------------------

::: toolkit/components/telemetry/docs/data/main-ping.rst
@@ +111,5 @@
>      }
>  
> +histograms and keyedHistograms
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +This section contains histograms and keyed histograms accumulated on content processes. Histograms for which Accumulate() is called on a content child process have different character than parent histograms. For instance, ``GC_MS`` will be much different in ``processes.content`` as it has to contend with web content, whereas the instance in ``payload.histograms`` has only to contend with browser JS. Also, some histograms may be absent if Accumulate() is never called from a content child process (``EVENTLOOP_UI_ACTIVITY`` is parent-process-only).

Nit: Instead of Accumulate(), lets say "if it was never recorded from ...".
People reading the documentation don't need to know about client side mechanics.

Comment 6

[Chris H-C :chutten]

Attachment: 0001-bug-1290027-Update-main-ping-docs-for-child-telemetr.patch

Comment 7

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/mozilla-inbound/rev/fe56ce42df42
Update "main" ping docs for child telemetry aggregation. r=gfritzsche

Comment 8

[Sebastian Hengst [:aryx] (needinfo me if it's about an intermittent or backout)]

Backed out for build bustage:

    2c7ef95c2785 SH Backed out changeset 74b9b3f4ce25 (bug 1218576) for build bustage. r=backout on a CLOSED TREE
    d9deb379d830 SH Backed out changeset 7537a79e91a4 (bug 1218577)
    b64e58e453e1 SH Backed out changeset 2310da8e4942 (bug 1218576)
    c249998a085f SH Backed out changeset cd8049475224 (bug 1218576)
    6a4b7a63125d SH Backed out changeset 6e4a7610406a (bug 1218576)
    f327e2486a4b SH Backed out changeset 2d375de64477 (bug 1218576)
    ac368b44eb34 SH Backed out changeset 59b0fb3fa328 (bug 1218576)
    1092ce552e86 SH Backed out changeset 0397f79f86ad (bug 1218576)
    70b93415fbef SH Backed out changeset 283cee5fb8a7 (bug 1218576)
    7e6a9af6246b SH Backed out changeset 7f8e3d336e2f (bug 1218576)
    20775bc718db SH Backed out changeset aee17ede1c0e (bug 1218576)
    9470c7a31cf2 SH Backed out changeset 80b0680f916f (bug 1218576)
    452bab4b12e9 SH Backed out changeset 3c5d66ad69a0 (bug 1218576)
    53f5c4b914c4 SH Backed out changeset ce72d25d0c5b (bug 1218576)
    188b32f8df91 SH Backed out changeset 3c606cacdd1d (bug 1277504)
    15ad29361e48 SH Backed out changeset fe56ce42df42 (bug 1290027)

Push with failures: https://treeherder.mozilla.org/#/jobs?repo=mozilla-inbound&revision=fe56ce42df420209cc940b2e88b676495c933d00

Comment 9

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/mozilla-inbound/rev/70b7f7e885c7
Update "main" ping docs for child telemetry aggregation. r=gfritzsche

Comment 10

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/mozilla-inbound/rev/5acdf0d2a029
Update "main" ping docs for child telemetry aggregation. r=gfritzsche

Comment 11

[Sebastian Hengst [:aryx] (needinfo me if it's about an intermittent or backout)]

Backed this out together with bug 1218576 and relanded it.

Comment 12

[Pulsebot]

Backout by [e-mail]:
https://hg.mozilla.org/integration/mozilla-inbound/rev/11d27b5c2820
Backed out changeset 70b7f7e885c7 for crashing in xpcshell test test_httpsuspend_wrap.js. r=backout

Comment 13

[Ryan VanderMeulen [:RyanVM]]

https://hg.mozilla.org/mozilla-central/rev/5acdf0d2a029

Comment 14

[Chris H-C :chutten]

Documentation relanded independently.