1124212 - Create telemetry documentation in-tree

Status: RESOLVED FIXED

(Toolkit :: Telemetry, defect)

Description

[Georg Fritzsche [:gfritzsche]]

Once the ping specifications etc. are finalized, we should start putting them into proper documentation.
I suggest we start using in-tree documentation for telemetry too.

Comment 1

[Georg Fritzsche [:gfritzsche]]

Attachment: First stub

Comment 2

[Georg Fritzsche [:gfritzsche]]

Attachment: First stub

Comment 3

[Georg Fritzsche [:gfritzsche]]

Attachment: Stub

Comment 4

[Mark Reid [:mreid]]

Please also document the submission process, particularly any retry policy.

Comment 5

[Georg Fritzsche [:gfritzsche]]

Attachment: Stub v2

Integrated the latest versions from the spec bugs.

We probably should split out the common ping / environment / main ping sections into separate pages.

Comment 6

[Georg Fritzsche [:gfritzsche]]

Attachment: In-tree telemetry documentation

While this might be not perfect yet, i think it's a good start. We can from here expand & update it from upcoming bugs.
I split this more up into sub-pages now and expanded a little on background and behavior.

This is generated with |mach build-docs| and can be found in |<objdir>/docs/html/toolkit/components/telemetry/telemetry/index.html|. After landing it will be part of |https://ci.mozilla.org/job/mozilla-central-docs/Tree_Documentation/|.

Comment 7

[Vladan Djeric (:vladan)]

Comment on attachment 8561560 [details] [diff] [review]
In-tree telemetry documentation

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

::: toolkit/components/telemetry/docs/common-ping.rst
@@ +20,5 @@
> +      type: <string>, // "main", "activation", "deletion", ...
> +      id: <UUID>, // a UUID that identifies this ping
> +      creationDate: <ISO date>, // the date the ping was generated
> +      version: <number>, // the version of the ping format, currently 2
> +      

accidental trailing space or needed?

@@ +31,5 @@
> +        platformVersion: <string>, // "35.0"
> +        xpcomAbi: <string>, // e.g. "x86-msvc"
> +        channel: <string>, // "beta"
> +      },
> +      

ditto

::: toolkit/components/telemetry/docs/environment.rst
@@ +27,5 @@
> +        blocklistEnabled: <bool>, // false on failure
> +        isDefaultBrowser: <bool>, // null on failure
> +        e10sEnabled: <bool>, // false on failure
> +        telemetryEnabled: <bool>, // false on failure
> +        locale: <string>, // "it" or null on failure

why "it" on failure?

::: toolkit/components/telemetry/docs/main-ping.rst
@@ +1,5 @@
> +
> +"main" ping
> +===========
> +
> +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.

nit: consistent capitalization of Telemetry

@@ +11,5 @@
> +* ``shutdown`` - triggered when the browser session ends
> +* ``daily`` - a session split triggered in 24h hour intervals at local 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 import measurements for those subsessions.

"import" measurements? important?

::: toolkit/components/telemetry/docs/pings.rst
@@ +3,5 @@
> +=====================
> +Telemetry pings
> +=====================
> +
> +A *telemetry ping* is the data that we send to Mozillas telemetry servers.

Telemetry capitalization

Comment 8

[Georg Fritzsche [:gfritzsche]]

(In reply to Vladan Djeric (:vladan) from comment #7)
> ::: toolkit/components/telemetry/docs/common-ping.rst
> @@ +20,5 @@
> > +      type: <string>, // "main", "activation", "deletion", ...
> > +      id: <UUID>, // a UUID that identifies this ping
> > +      creationDate: <ISO date>, // the date the ping was generated
> > +      version: <number>, // the version of the ping format, currently 2
> > +      
> 
> accidental trailing space or needed?

This was unneeded, fixed.

> ::: toolkit/components/telemetry/docs/environment.rst
> @@ +27,5 @@
> > +        blocklistEnabled: <bool>, // false on failure
> > +        isDefaultBrowser: <bool>, // null on failure
> > +        e10sEnabled: <bool>, // false on failure
> > +        telemetryEnabled: <bool>, // false on failure
> > +        locale: <string>, // "it" or null on failure
> 
> why "it" on failure?

This is confusingly written. Changed to: e.g. "it", null on failure

> @@ +11,5 @@
> > +* ``shutdown`` - triggered when the browser session ends
> > +* ``daily`` - a session split triggered in 24h hour intervals at local 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 import measurements for those subsessions.
> 
> "import" measurements? important?

Yes, fixed.

Comment 9

[Georg Fritzsche [:gfritzsche]]

Attachment: In-tree telemetry documentation

Comment 10

[Georg Fritzsche [:gfritzsche]]

I landed this now so we can start to point people to the docs:
https://hg.mozilla.org/integration/mozilla-inbound/rev/5688e50ade0a

Additional changes/update will happen on the bugs that deviate from this version.

Comment 11

[Ryan VanderMeulen [:RyanVM]]

https://hg.mozilla.org/mozilla-central/rev/5688e50ade0a