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.

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

Integrated the latest versions from the spec bugs. We probably should split out the common ping / environment / main ping sections into separate pages.

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 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

(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.

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.