Bug 1246816 - Add docs for profileDate. r=gfritzsche
authorMichael Comella <michael.l.comella@gmail.com>
Thu, 31 Mar 2016 15:40:38 -0700
changeset 292108 163ec1ec0f25e482a9c5156581887744f1f3fbb7
parent 292107 0bdc00213180d671c58bd10e2e7e79853d481532
child 292109 1725b460c3e0de97590cb8764df9ace9115b813e
push id74762
push usercbook@mozilla.com
push dateThu, 07 Apr 2016 09:56:20 +0000
treeherdermozilla-inbound@772253c53374 [default view] [failures only]
perfherder[talos] [build metrics] [platform microbench] (compared to previous push)
reviewersgfritzsche
bugs1246816
milestone48.0a1
first release with
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
last release without
nightly linux32
nightly linux64
nightly mac
nightly win32
nightly win64
Bug 1246816 - Add docs for profileDate. r=gfritzsche MozReview-Commit-ID: 3KvGVjNev2r
toolkit/components/telemetry/docs/core-ping.rst
--- a/toolkit/components/telemetry/docs/core-ping.rst
+++ b/toolkit/components/telemetry/docs/core-ping.rst
@@ -20,17 +20,17 @@ Submission will be per the Edge server s
 * ``appBuildID`` is the build number
 
 Note: Counts below (e.g. search & usage times) are “since the last
 ping”, not total for the whole application lifetime.
 
 Structure::
 
     {
-      "v": 2, // ping format version
+      "v": 3, // ping format version
       "clientId": <string>, // client id, e.g.
                             // "c641eacf-c30c-4171-b403-f077724e848a"
       "seq": <positive integer>, // running ping counter, e.g. 3
       "locale": <string>, // application locale, e.g. "en-US"
       "os": <string>, // OS name.
       "osversion": <string>, // OS version.
       "device": <string>, // Build.MANUFACTURER + " - " + Build.MODEL
                           // where manufacturer is truncated to 12 characters
@@ -75,16 +75,28 @@ engine from the search plugins (in order
 * From the localized plugins shipped with the browser
 * The third-party plugins that are installed in the profile directory
 
 If the plugins fail to create a search engine instance, this field is also
 ``null``.
 
 profileDate
 ~~~~~~~~~~~
+On Android, this value is created at profile creation time and retrieved or,
+for legacy profiles, taken from the package install time (note: this is not the
+same exact metric as profile creation time but we compromised in favor of ease
+of implementation).
 
-This field may be missing if `times.json` does not exist or could not be read from the profile.
-`Bug 1246816 <https://bugzilla.mozilla.org/show_bug.cgi?id=1246816>`_ will fix that with a fallback mechanism.
+Additionally on Android, this field may be ``null`` in the unlikely event that
+all of the following events occur:
+
+#. The times.json file does not exist
+#. The package install date could not be persisted to disk
+
+The reason we don't just return the package install time even if the date could
+not be persisted to disk is to ensure the value doesn't change once we start
+sending it: we only want to send consistent values.
 
 Version history
 ---------------
+* v3: ``profileDate`` will return package install time when times.json is not available
 * v2: added ``defaultSearch``
 * v1: initial version