Closed Bug 1124212 Opened 5 years ago Closed 5 years ago

Create telemetry documentation in-tree

Categories

(Toolkit :: Telemetry, defect)

defect
Not set

Tracking

()

RESOLVED FIXED
mozilla38
Tracking Status
firefox38 --- fixed

People

(Reporter: gfritzsche, Assigned: gfritzsche)

References

Details

(Whiteboard: [ready])

Attachments

(1 file, 5 obsolete files)

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.
Attached patch First stub (obsolete) — Splinter Review
Attached patch First stub (obsolete) — Splinter Review
Attachment #8552487 - Attachment is obsolete: true
Attached patch Stub (obsolete) — Splinter Review
Attachment #8552492 - Attachment is obsolete: true
Assignee: nobody → gfritzsche
Please also document the submission process, particularly any retry policy.
Attached patch Stub v2 (obsolete) — Splinter Review
Integrated the latest versions from the spec bugs.

We probably should split out the common ping / environment / main ping sections into separate pages.
Attachment #8552634 - Attachment is obsolete: true
Attached patch In-tree telemetry documentation (obsolete) — Splinter Review
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/|.
Attachment #8558457 - Attachment is obsolete: true
Attachment #8561560 - Flags: review?(vdjeric)
Status: NEW → ASSIGNED
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
Attachment #8561560 - Flags: review?(vdjeric) → review+
(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.
Attachment #8561560 - Attachment is obsolete: true
Attachment #8562145 - Flags: review+
Whiteboard: [ready]
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.
https://hg.mozilla.org/mozilla-central/rev/5688e50ade0a
Status: ASSIGNED → RESOLVED
Closed: 5 years ago
Resolution: --- → FIXED
Target Milestone: --- → mozilla38
You need to log in before you can comment on or make changes to this bug.