michael@0: .. _healthreport_dataformat:
michael@0: 
michael@0: ==============
michael@0: Payload Format
michael@0: ==============
michael@0: 
michael@0: Currently, the Firefox Health Report is submitted as a compressed JSON
michael@0: document. The root JSON element is an object. A *version* field defines
michael@0: the version of the payload which in turn defines the expected contents
michael@0: the object.
michael@0: 
michael@0: As of 2013-07-03, desktop submits Version 2, and Firefox for Android submits
michael@0: Version 3 payloads.
michael@0: 
michael@0: Version 3
michael@0: =========
michael@0: 
michael@0: Version 3 is a complete rebuild of the document format. Events are tracked in
michael@0: an "environment". Environments are computed from a large swath of local data
michael@0: (e.g., add-ons, CPU count, versions), and a new environment comes into being
michael@0: when one of its attributes changes.
michael@0: 
michael@0: Client documents, then, will include descriptions of many environments, and
michael@0: measurements will be attributed to one particular environment.
michael@0: 
michael@0: A map of environments is present at the top level of the document, with the
michael@0: current named "current" in the map. Each environment has a hash identifier and
michael@0: a set of attributes. The current environment is completely described, and has
michael@0: its hash present in a "hash" attribute. All other environments are represented
michael@0: as a tree diff from the current environment, with their hash as the key in the
michael@0: "environments" object.
michael@0: 
michael@0: A removed add-on has the value 'null'.
michael@0: 
michael@0: There is no "last" data at present.
michael@0: 
michael@0: Daily data is hierarchical: by day, then by environment, and then by
michael@0: measurement, and is present in "data", just as in v2.
michael@0: 
michael@0: Leading by example::
michael@0: 
michael@0:     {
michael@0:       "lastPingDate": "2013-06-29",
michael@0:       "thisPingDate": "2013-07-03",
michael@0:       "version": 3,
michael@0:       "environments": {
michael@0:         "current": {
michael@0:           "org.mozilla.sysinfo.sysinfo": {
michael@0:             "memoryMB": 1567,
michael@0:             "cpuCount": 4,
michael@0:             "architecture": "armeabi-v7a",
michael@0:             "_v": 1,
michael@0:             "version": "4.1.2",
michael@0:             "name": "Android"
michael@0:           },
michael@0:           "org.mozilla.profile.age": {
michael@0:             "_v": 1,
michael@0:             "profileCreation": 15827
michael@0:           },
michael@0:           "org.mozilla.addons.active": {
michael@0:             "QuitNow@TWiGSoftware.com": {
michael@0:               "appDisabled": false,
michael@0:               "userDisabled": false,
michael@0:               "scope": 1,
michael@0:               "updateDay": 15885,
michael@0:               "foreignInstall": false,
michael@0:               "hasBinaryComponents": false,
michael@0:               "blocklistState": 0,
michael@0:               "type": "extension",
michael@0:               "installDay": 15885,
michael@0:               "version": "1.18.02"
michael@0:             },
michael@0:             "{dbbf9331-b713-6eda-1006-205efead09dc}": {
michael@0:               "appDisabled": false,
michael@0:               "userDisabled": "askToActivate",
michael@0:               "scope": 8,
michael@0:               "updateDay": 15779,
michael@0:               "foreignInstall": true,
michael@0:               "blocklistState": 0,
michael@0:               "type": "plugin",
michael@0:               "installDay": 15779,
michael@0:               "version": "11.1 r115"
michael@0:             },
michael@0:             "desktopbydefault@bnicholson.mozilla.org": {
michael@0:               "appDisabled": false,
michael@0:               "userDisabled": true,
michael@0:               "scope": 1,
michael@0:               "updateDay": 15870,
michael@0:               "foreignInstall": false,
michael@0:               "hasBinaryComponents": false,
michael@0:               "blocklistState": 0,
michael@0:               "type": "extension",
michael@0:               "installDay": 15870,
michael@0:               "version": "1.1"
michael@0:             },
michael@0:             "{6e092a7f-ba58-4abb-88c1-1a4e50b217e4}": {
michael@0:               "appDisabled": false,
michael@0:               "userDisabled": false,
michael@0:               "scope": 1,
michael@0:               "updateDay": 15828,
michael@0:               "foreignInstall": false,
michael@0:               "hasBinaryComponents": false,
michael@0:               "blocklistState": 0,
michael@0:               "type": "extension",
michael@0:               "installDay": 15828,
michael@0:               "version": "1.1.0"
michael@0:             },
michael@0:             "{46551EC9-40F0-4e47-8E18-8E5CF550CFB8}": {
michael@0:               "appDisabled": false,
michael@0:               "userDisabled": true,
michael@0:               "scope": 1,
michael@0:               "updateDay": 15879,
michael@0:               "foreignInstall": false,
michael@0:               "hasBinaryComponents": false,
michael@0:               "blocklistState": 0,
michael@0:               "type": "extension",
michael@0:               "installDay": 15879,
michael@0:               "version": "1.3.2"
michael@0:             },
michael@0:             "_v": 1
michael@0:           },
michael@0:           "org.mozilla.appInfo.appinfo": {
michael@0:             "_v": 3,
michael@0:             "appLocale": "en_us",
michael@0:             "osLocale": "en_us",
michael@0:             "distribution": "",
michael@0:             "acceptLangIsUserSet": 0,
michael@0:             "isTelemetryEnabled": 1,
michael@0:             "isBlocklistEnabled": 1
michael@0:           },
michael@0:           "geckoAppInfo": {
michael@0:             "updateChannel": "nightly",
michael@0:             "id": "{aa3c5121-dab2-40e2-81ca-7ea25febc110}",
michael@0:             "os": "Android",
michael@0:             "platformBuildID": "20130703031323",
michael@0:             "platformVersion": "25.0a1",
michael@0:             "vendor": "Mozilla",
michael@0:             "name": "fennec",
michael@0:             "xpcomabi": "arm-eabi-gcc3",
michael@0:             "appBuildID": "20130703031323",
michael@0:             "_v": 1,
michael@0:             "version": "25.0a1"
michael@0:           },
michael@0:           "hash": "tB4Pnnep9yTxnMDymc3dAB2RRB0=",
michael@0:           "org.mozilla.addons.counts": {
michael@0:             "extension": 4,
michael@0:             "plugin": 1,
michael@0:             "_v": 1,
michael@0:             "theme": 0
michael@0:           }
michael@0:         },
michael@0:         "k2O3hlreMeS7L1qtxeMsYWxgWWQ=": {
michael@0:           "geckoAppInfo": {
michael@0:             "platformBuildID": "20130630031138",
michael@0:             "appBuildID": "20130630031138",
michael@0:             "_v": 1
michael@0:           },
michael@0:           "org.mozilla.appInfo.appinfo": {
michael@0:             "_v": 2,
michael@0:           }
michael@0:         },
michael@0:         "1+KN9TutMpzdl4TJEl+aCxK+xcw=": {
michael@0:           "geckoAppInfo": {
michael@0:             "platformBuildID": "20130626031100",
michael@0:             "appBuildID": "20130626031100",
michael@0:             "_v": 1
michael@0:           },
michael@0:           "org.mozilla.addons.active": {
michael@0:             "QuitNow@TWiGSoftware.com": null,
michael@0:             "{dbbf9331-b713-6eda-1006-205efead09dc}": null,
michael@0:             "desktopbydefault@bnicholson.mozilla.org": null,
michael@0:             "{6e092a7f-ba58-4abb-88c1-1a4e50b217e4}": null,
michael@0:             "{46551EC9-40F0-4e47-8E18-8E5CF550CFB8}": null,
michael@0:             "_v": 1
michael@0:           },
michael@0:           "org.mozilla.addons.counts": {
michael@0:             "extension": 0,
michael@0:             "plugin": 0,
michael@0:             "_v": 1
michael@0:           }
michael@0:         }
michael@0:       },
michael@0:       "data": {
michael@0:         "last": {},
michael@0:         "days": {
michael@0:           "2013-07-03": {
michael@0:             "tB4Pnnep9yTxnMDymc3dAB2RRB0=": {
michael@0:               "org.mozilla.appSessions": {
michael@0:                 "normal": [
michael@0:                   {
michael@0:                     "r": "P",
michael@0:                     "d": 2,
michael@0:                     "sj": 653
michael@0:                   },
michael@0:                   {
michael@0:                     "r": "P",
michael@0:                     "d": 22
michael@0:                   },
michael@0:                   {
michael@0:                     "r": "P",
michael@0:                     "d": 5
michael@0:                   },
michael@0:                   {
michael@0:                     "r": "P",
michael@0:                     "d": 0
michael@0:                   },
michael@0:                   {
michael@0:                     "r": "P",
michael@0:                     "sg": 3560,
michael@0:                     "d": 171,
michael@0:                     "sj": 518
michael@0:                   },
michael@0:                   {
michael@0:                     "r": "P",
michael@0:                     "d": 16
michael@0:                   },
michael@0:                   {
michael@0:                     "r": "P",
michael@0:                     "d": 1079
michael@0:                   }
michael@0:                 ],
michael@0:                 "_v": "4"
michael@0:               }
michael@0:             },
michael@0:             "k2O3hlreMeS7L1qtxeMsYWxgWWQ=": {
michael@0:               "org.mozilla.appSessions": {
michael@0:                 "normal": [
michael@0:                   {
michael@0:                     "r": "P",
michael@0:                     "d": 27
michael@0:                   },
michael@0:                   {
michael@0:                     "r": "P",
michael@0:                     "d": 19
michael@0:                   },
michael@0:                   {
michael@0:                     "r": "P",
michael@0:                     "d": 55
michael@0:                   }
michael@0:                 ],
michael@0:                 "_v": "4"
michael@0:               },
michael@0:               "org.mozilla.searches.counts": {
michael@0:                 "bartext": {
michael@0:                   "google": 1
michael@0:                 },
michael@0:                 "_v": "4"
michael@0:               },
michael@0:               "org.mozilla.experiment": {
michael@0:                 "lastActive": "some.experiment.id"
michael@0:                 "_v": "1"
michael@0:               }
michael@0:             }
michael@0:           }
michael@0:         }
michael@0:       }
michael@0:     }
michael@0: 
michael@0: App sessions in Version 3
michael@0: -------------------------
michael@0: 
michael@0: Sessions are divided into "normal" and "abnormal". Session objects are stored as discrete JSON::
michael@0: 
michael@0:     "org.mozilla.appSessions": {
michael@0:       _v: 4,
michael@0:       "normal": [
michael@0:         {"r":"P", "d": 123},
michael@0:       ],
michael@0:       "abnormal": [
michael@0:         {"r":"A", "oom": true, "stopped": false}
michael@0:       ]
michael@0:     }
michael@0: 
michael@0: Keys are:
michael@0: 
michael@0: "r"
michael@0:     reason. Values are "P" (activity paused), "A" (abnormal termination).
michael@0: "d"
michael@0:     duration. Value in seconds.
michael@0: "sg"
michael@0:     Gecko startup time (msec). Present if this is a clean launch. This
michael@0:     corresponds to the telemetry timer *FENNEC_STARTUP_TIME_GECKOREADY*.
michael@0: "sj"
michael@0:     Java activity init time (msec). Present if this is a clean launch. This
michael@0:     corresponds to the telemetry timer *FENNEC_STARTUP_TIME_JAVAUI*,
michael@0:     and includes initialization tasks beyond initial
michael@0:     *onWindowFocusChanged*.
michael@0: 
michael@0: Abnormal terminations will be missing a duration and will feature these keys:
michael@0: 
michael@0: "oom"
michael@0:     was the session killed by an OOM exception?
michael@0: "stopped"
michael@0:     was the session stopped gently?
michael@0: 
michael@0: Version 3.1
michael@0: -----------
michael@0: 
michael@0: As of Firefox 27, *appinfo* is now bumped to v3, including *osLocale*,
michael@0: *appLocale* (currently always the same as *osLocale*), *distribution* (a string
michael@0: containing the distribution ID and version, separated by a colon), and
michael@0: *acceptLangIsUserSet*, an integer-boolean that describes whether the user set
michael@0: an *intl.accept_languages* preference.
michael@0: 
michael@0: The search counts measurement is now at version 5, which indicates that
michael@0: non-partner searches are recorded. You'll see identifiers like "other-Foo Bar"
michael@0: rather than "other".
michael@0: 
michael@0: Other notable differences from Version 2
michael@0: ----------------------------------------
michael@0: 
michael@0: * There is no default browser indicator on Android.
michael@0: * Add-ons include a *blocklistState* attribute, as returned by AddonManager.
michael@0: * Searches are now version 4, and are hierarchical: how the search was started
michael@0:   (bartext, barkeyword, barsuggest), and then counts per provider.
michael@0: 
michael@0: Version 2
michael@0: =========
michael@0: 
michael@0: Version 2 is the same as version 1 with the exception that it has an additional
michael@0: top-level field, *geckoAppInfo*, which contains basic application info.
michael@0: 
michael@0: geckoAppInfo
michael@0: ------------
michael@0: 
michael@0: This field is an object that is a simple map of string keys and values
michael@0: describing basic application metadata. It is very similar to the *appinfo*
michael@0: measurement in the *last* section. The difference is this field is almost
michael@0: certainly guaranteed to exist whereas the one in the data part of the
michael@0: payload may be omitted in certain scenarios (such as catastrophic client
michael@0: error).
michael@0: 
michael@0: Its keys are as follows:
michael@0: 
michael@0: appBuildID
michael@0:     The build ID/date of the application. e.g. "20130314113542".
michael@0: 
michael@0: version
michael@0:     The value of nsXREAppData.version. This is the application's version. e.g.
michael@0:     "21.0.0".
michael@0: 
michael@0: vendor
michael@0:     The value of nsXREAppData.vendor. Can be empty an empty string. For
michael@0:     official Mozilla builds, this will be "Mozilla".
michael@0: 
michael@0: name
michael@0:     The value of nsXREAppData.name. For official Firefox builds, this
michael@0:     will be "Firefox".
michael@0: 
michael@0: id
michael@0:     The value of nsXREAppData.ID.
michael@0: 
michael@0: platformVersion
michael@0:     The version of the Gecko platform (as opposed to the app version). For
michael@0:     Firefox, this is almost certainly equivalent to the *version* field.
michael@0: 
michael@0: platformBuildID
michael@0:     The build ID/date of the Gecko platfor (as opposed to the app version).
michael@0:     This is commonly equivalent to *appBuildID*.
michael@0: 
michael@0: os
michael@0:     The name of the operating system the application is running on.
michael@0: 
michael@0: xpcomabi
michael@0:     The binary architecture of the build.
michael@0: 
michael@0: updateChannel
michael@0:     The name of the channel used for application updates. Official Mozilla
michael@0:     builds have one of the values {release, beta, aurora, nightly}. Local and
michael@0:     test builds have *default* as the channel.
michael@0: 
michael@0: Version 1
michael@0: =========
michael@0: 
michael@0: Top-level Properties
michael@0: --------------------
michael@0: 
michael@0: The main JSON object contains the following properties:
michael@0: 
michael@0: lastPingDate
michael@0:     UTC date of the last upload. If this is the first upload from this client,
michael@0:     this will not be present.
michael@0: 
michael@0: thisPingDate
michael@0:     UTC date when this payload was constructed.
michael@0: 
michael@0: version
michael@0:     Integer version of this payload format. Currently only 1 is defined.
michael@0: 
michael@0: clientID
michael@0:     An identifier that identifies the client that is submitting data.
michael@0: 
michael@0:     This property may not be present in older clients.
michael@0: 
michael@0:     See :ref:`healthreport_identifiers` for more info on identifiers.
michael@0: 
michael@0: clientIDVersion
michael@0:     Integer version associated with the generation semantics for the
michael@0:     ``clientID``.
michael@0: 
michael@0:     If the value is ``1``, ``clientID`` is a randomly-generated UUID.
michael@0: 
michael@0:     This property may not be present in older clients.
michael@0: 
michael@0: data
michael@0:     Object holding data constituting health report.
michael@0: 
michael@0: Data Properties
michael@0: ---------------
michael@0: 
michael@0: The bulk of the health report is contained within the *data* object. This
michael@0: object has the following keys:
michael@0: 
michael@0: days
michael@0:    Object mapping UTC days to measurements from that day. Keys are in the
michael@0:    *YYYY-MM-DD* format. e.g. "2013-03-14"
michael@0: 
michael@0: last
michael@0:    Object mapping measurement names to their values.
michael@0: 
michael@0: 
michael@0: The value of *days* and *last* are objects mapping measurement names to that
michael@0: measurement's values. The values are always objects. Each object contains
michael@0: a *_v* property. This property defines the version of this measurement.
michael@0: Additional non-underscore-prefixed properties are defined by the measurement
michael@0: itself (see sections below).
michael@0: 
michael@0: Example
michael@0: -------
michael@0: 
michael@0: Here is an example JSON document for version 1::
michael@0: 
michael@0:     {
michael@0:       "version": 1,
michael@0:       "thisPingDate": "2013-03-11",
michael@0:       "lastPingDate": "2013-03-10",
michael@0:       "data": {
michael@0:         "last": {
michael@0:           "org.mozilla.addons.active": {
michael@0:             "masspasswordreset@johnathan.nightingale": {
michael@0:               "userDisabled": false,
michael@0:               "appDisabled": false,
michael@0:               "version": "1.05",
michael@0:               "type": "extension",
michael@0:               "scope": 1,
michael@0:               "foreignInstall": false,
michael@0:               "hasBinaryComponents": false,
michael@0:               "installDay": 14973,
michael@0:               "updateDay": 15317
michael@0:             },
michael@0:             "places-maintenance@bonardo.net": {
michael@0:               "userDisabled": false,
michael@0:               "appDisabled": false,
michael@0:               "version": "1.3",
michael@0:               "type": "extension",
michael@0:               "scope": 1,
michael@0:               "foreignInstall": false,
michael@0:               "hasBinaryComponents": false,
michael@0:               "installDay": 15268,
michael@0:               "updateDay": 15379
michael@0:             },
michael@0:             "_v": 1
michael@0:           },
michael@0:           "org.mozilla.appInfo.appinfo": {
michael@0:             "_v": 1,
michael@0:             "appBuildID": "20130309030841",
michael@0:             "distributionID": "",
michael@0:             "distributionVersion": "",
michael@0:             "hotfixVersion": "",
michael@0:             "id": "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}",
michael@0:             "locale": "en-US",
michael@0:             "name": "Firefox",
michael@0:             "os": "Darwin",
michael@0:             "platformBuildID": "20130309030841",
michael@0:             "platformVersion": "22.0a1",
michael@0:             "updateChannel": "nightly",
michael@0:             "vendor": "Mozilla",
michael@0:             "version": "22.0a1",
michael@0:             "xpcomabi": "x86_64-gcc3"
michael@0:           },
michael@0:           "org.mozilla.profile.age": {
michael@0:             "_v": 1,
michael@0:             "profileCreation": 12444
michael@0:           },
michael@0:           "org.mozilla.appSessions.current": {
michael@0:             "_v": 3,
michael@0:             "startDay": 15773,
michael@0:             "activeTicks": 522,
michael@0:             "totalTime": 70858,
michael@0:             "main": 1245,
michael@0:             "firstPaint": 2695,
michael@0:             "sessionRestored": 3436
michael@0:           },
michael@0:           "org.mozilla.sysinfo.sysinfo": {
michael@0:             "_v": 1,
michael@0:             "cpuCount": 8,
michael@0:             "memoryMB": 16384,
michael@0:             "architecture": "x86-64",
michael@0:             "name": "Darwin",
michael@0:             "version": "12.2.1"
michael@0:           }
michael@0:         },
michael@0:         "days": {
michael@0:           "2013-03-11": {
michael@0:             "org.mozilla.addons.counts": {
michael@0:               "_v": 1,
michael@0:               "extension": 15,
michael@0:               "plugin": 12,
michael@0:               "theme": 1
michael@0:             },
michael@0:             "org.mozilla.places.places": {
michael@0:               "_v": 1,
michael@0:               "bookmarks": 757,
michael@0:               "pages": 104858
michael@0:             },
michael@0:             "org.mozilla.appInfo.appinfo": {
michael@0:               "_v": 1,
michael@0:               "isDefaultBrowser": 1
michael@0:             }
michael@0:           },
michael@0:           "2013-03-10": {
michael@0:             "org.mozilla.addons.counts": {
michael@0:               "_v": 1,
michael@0:               "extension": 15,
michael@0:               "plugin": 12,
michael@0:               "theme": 1
michael@0:             },
michael@0:             "org.mozilla.places.places": {
michael@0:               "_v": 1,
michael@0:               "bookmarks": 757,
michael@0:               "pages": 104857
michael@0:             },
michael@0:             "org.mozilla.searches.counts": {
michael@0:               "_v": 1,
michael@0:               "google.urlbar": 4
michael@0:             },
michael@0:             "org.mozilla.appInfo.appinfo": {
michael@0:               "_v": 1,
michael@0:               "isDefaultBrowser": 1
michael@0:             }
michael@0:           }
michael@0:         }
michael@0:       }
michael@0:     }
michael@0: 
michael@0: Measurements
michael@0: ============
michael@0: 
michael@0: The bulk of payloads consists of measurement data. An individual measurement
michael@0: is merely a collection of related values e.g. *statistics about the Places
michael@0: database* or *system information*.
michael@0: 
michael@0: Each measurement has an integer version number attached. When the fields in
michael@0: a measurement or the semantics of data within that measurement change, the
michael@0: version number is incremented.
michael@0: 
michael@0: All measurements are defined alphabetically in the sections below.
michael@0: 
michael@0: org.mozilla.addons.addons
michael@0: -------------------------
michael@0: 
michael@0: This measurement contains information about the currently-installed add-ons.
michael@0: 
michael@0: Version 2
michael@0: ^^^^^^^^^
michael@0: 
michael@0: This version adds the human-readable fields *name* and *description*, both
michael@0: coming directly from the Addon instance as most properties in version 1.
michael@0: Also, all plugin details are now in org.mozilla.addons.plugins.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: The measurement object is a mapping of add-on IDs to objects containing
michael@0: add-on metadata.
michael@0: 
michael@0: Each add-on contains the following properties:
michael@0: 
michael@0: * userDisabled
michael@0: * appDisabled
michael@0: * version
michael@0: * type
michael@0: * scope
michael@0: * foreignInstall
michael@0: * hasBinaryComponents
michael@0: * installDay
michael@0: * updateDay
michael@0: 
michael@0: With the exception of *installDay* and *updateDay*, all these properties
michael@0: come direct from the Addon instance. See https://developer.mozilla.org/en-US/docs/Addons/Add-on_Manager/Addon.
michael@0: *installDay* and *updateDay* are the number of days since UNIX epoch of
michael@0: the add-ons *installDate* and *updateDate* properties, respectively.
michael@0: 
michael@0: Notes
michael@0: ^^^^^
michael@0: 
michael@0: Add-ons that have opted out of AMO updates via the
michael@0: *extensions._id_.getAddons.cache.enabled* preference are, since Bug 868306
michael@0: (Firefox 24), included in the list of submitted add-ons.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: ::
michael@0: 
michael@0:     "org.mozilla.addons.addons": {
michael@0:       "_v": 2,
michael@0:       "{d10d0bf8-f5b5-c8b4-a8b2-2b9879e08c5d}": {
michael@0:         "userDisabled": false,
michael@0:         "appDisabled": false,
michael@0:         "name": "Adblock Plus",
michael@0:         "version": "2.4.1",
michael@0:         "type": "extension",
michael@0:         "scope": 1,
michael@0:         "description": "Ads were yesterday!",
michael@0:         "foreignInstall": false,
michael@0:         "hasBinaryComponents": false,
michael@0:         "installDay": 16093,
michael@0:         "updateDay": 16093
michael@0:       },
michael@0:       "{e4a8a97b-f2ed-450b-b12d-ee082ba24781}": {
michael@0:         "userDisabled": true,
michael@0:         "appDisabled": false,
michael@0:         "name": "Greasemonkey",
michael@0:         "version": "1.14",
michael@0:         "type": "extension",
michael@0:         "scope": 1,
michael@0:         "description": "A User Script Manager for Firefox",
michael@0:         "foreignInstall": false,
michael@0:         "hasBinaryComponents": false,
michael@0:         "installDay": 16093,
michael@0:         "updateDay": 16093
michael@0:       }
michael@0:     }
michael@0: 
michael@0: org.mozilla.addons.plugins
michael@0: -------------------------
michael@0: 
michael@0: This measurement contains information about the currently-installed plugins.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: The measurement object is a mapping of plugin IDs to objects containing
michael@0: plugin metadata.
michael@0: 
michael@0: The plugin ID is constructed of the plugins filename, name, version and
michael@0: description. Every plugin has at least a filename and a name.
michael@0: 
michael@0: Each plugin contains the following properties:
michael@0: 
michael@0: * name
michael@0: * version
michael@0: * description
michael@0: * blocklisted
michael@0: * disabled
michael@0: * clicktoplay
michael@0: * mimeTypes
michael@0: * updateDay
michael@0: 
michael@0: With the exception of *updateDay* and *mimeTypes*, all these properties come
michael@0: directly from ``nsIPluginTag`` via ``nsIPluginHost``.
michael@0: *updateDay* is the number of days since UNIX epoch of the plugins last modified
michael@0: time.
michael@0: *mimeTypes* is the list of mimetypes the plugin supports, see
michael@0: ``nsIPluginTag.getMimeTypes()`.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "org.mozilla.addons.plugins": {
michael@0:       "_v": 1,
michael@0:       "Flash Player.plugin:Shockwave Flash:12.0.0.38:Shockwave Flash 12.0 r0": {
michael@0:         "mimeTypes": [
michael@0:           "application/x-shockwave-flash",
michael@0:           "application/futuresplash"
michael@0:         ],
michael@0:         "name": "Shockwave Flash",
michael@0:         "version": "12.0.0.38",
michael@0:         "description": "Shockwave Flash 12.0 r0",
michael@0:         "blocklisted": false,
michael@0:         "disabled": false,
michael@0:         "clicktoplay": false
michael@0:       },
michael@0:       "Default Browser.plugin:Default Browser Helper:537:Provides information about the default web browser": {
michael@0:         "mimeTypes": [
michael@0:           "application/apple-default-browser"
michael@0:         ],
michael@0:         "name": "Default Browser Helper",
michael@0:         "version": "537",
michael@0:         "description": "Provides information about the default web browser",
michael@0:         "blocklisted": false,
michael@0:         "disabled": true,
michael@0:         "clicktoplay": false
michael@0:       }
michael@0:     }
michael@0: 
michael@0: org.mozilla.addons.counts
michael@0: -------------------------
michael@0: 
michael@0: This measurement contains information about historical add-on counts.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: The measurement object consists of counts of different add-on types. The
michael@0: properties are:
michael@0: 
michael@0: extension
michael@0:     Integer count of installed extensions.
michael@0: plugin
michael@0:     Integer count of installed plugins.
michael@0: theme
michael@0:     Integer count of installed themes.
michael@0: lwtheme
michael@0:     Integer count of installed lightweigh themes.
michael@0: 
michael@0: Notes
michael@0: ^^^^^
michael@0: 
michael@0: Add-ons opted out of AMO updates are included in the counts. This differs from
michael@0: the behavior of the active add-ons measurement.
michael@0: 
michael@0: If no add-ons of a particular type are installed, the property for that type
michael@0: will not be present (as opposed to an explicit property with value of 0).
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "2013-03-14": {
michael@0:       "org.mozilla.addons.counts": {
michael@0:         "_v": 1,
michael@0:         "extension": 21,
michael@0:         "plugin": 4,
michael@0:         "theme": 1
michael@0:       }
michael@0:     }
michael@0: 
michael@0: 
michael@0: 
michael@0: org.mozilla.appInfo.appinfo
michael@0: ---------------------------
michael@0: 
michael@0: This measurement contains basic XUL application and Gecko platform
michael@0: information. It is reported in the *last* section.
michael@0: 
michael@0: Version 2
michael@0: ^^^^^^^^^
michael@0: 
michael@0: In addition to fields present in version 1, this version has the following
michael@0: fields appearing in the *days* section:
michael@0: 
michael@0: isBlocklistEnabled
michael@0:     Whether the blocklist ping is enabled. This is an integer, 0 or 1.
michael@0:     This does not indicate whether the blocklist ping was sent but merely
michael@0:     whether the application will try to send the blocklist ping.
michael@0: 
michael@0: isTelemetryEnabled
michael@0:     Whether Telemetry is enabled. This is an integer, 0 or 1.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: The measurement object contains mostly string values describing the
michael@0: current application and build. The properties are:
michael@0: 
michael@0: * vendor
michael@0: * name
michael@0: * id
michael@0: * version
michael@0: * appBuildID
michael@0: * platformVersion
michael@0: * platformBuildID
michael@0: * os
michael@0: * xpcomabi
michael@0: * updateChannel
michael@0: * distributionID
michael@0: * distributionVersion
michael@0: * hotfixVersion
michael@0: * locale
michael@0: * isDefaultBrowser
michael@0: 
michael@0: Notes
michael@0: ^^^^^
michael@0: 
michael@0: All of the properties appear in the *last* section except for
michael@0: *isDefaultBrowser*, which appears under *days*.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: This example comes from an official OS X Nightly build::
michael@0: 
michael@0:     "org.mozilla.appInfo.appinfo": {
michael@0:       "_v": 1,
michael@0:       "appBuildID": "20130311030946",
michael@0:       "distributionID": "",
michael@0:       "distributionVersion": "",
michael@0:       "hotfixVersion": "",
michael@0:       "id": "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}",
michael@0:       "locale": "en-US",
michael@0:       "name": "Firefox",
michael@0:       "os": "Darwin",
michael@0:       "platformBuildID": "20130311030946",
michael@0:       "platformVersion": "22.0a1",
michael@0:       "updateChannel": "nightly",
michael@0:       "vendor": "Mozilla",
michael@0:       "version": "22.0a1",
michael@0:       "xpcomabi": "x86_64-gcc3"
michael@0:     },
michael@0: 
michael@0: org.mozilla.appInfo.update
michael@0: --------------------------
michael@0: 
michael@0: This measurement contains information about the application update mechanism
michael@0: in the application.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: The following daily values are reported:
michael@0: 
michael@0: enabled
michael@0:     Whether automatic application update checking is enabled. 1 for yes,
michael@0:     0 for no.
michael@0: autoDownload
michael@0:     Whether automatic download of available updates is enabled.
michael@0: 
michael@0: Notes
michael@0: ^^^^^
michael@0: 
michael@0: This measurement was merged to mozilla-central for JS FHR on 2013-07-15.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "2013-07-15": {
michael@0:       "org.mozilla.appInfo.update": {
michael@0:         "_v": 1,
michael@0:         "enabled": 1,
michael@0:         "autoDownload": 1,
michael@0:       }
michael@0:     }
michael@0: 
michael@0: org.mozilla.appInfo.versions
michael@0: ----------------------------
michael@0: 
michael@0: This measurement contains a history of application version numbers.
michael@0: 
michael@0: Version 2
michael@0: ^^^^^^^^^
michael@0: 
michael@0: Version 2 reports more fields than version 1 and is not backwards compatible.
michael@0: The following fields are present in version 2:
michael@0: 
michael@0: appVersion
michael@0:     An array of application version strings.
michael@0: appBuildID
michael@0:     An array of application build ID strings.
michael@0: platformVersion
michael@0:     An array of platform version strings.
michael@0: platformBuildID
michael@0:     An array of platform build ID strings.
michael@0: 
michael@0: When the application is upgraded, the new version and/or build IDs are
michael@0: appended to their appropriate fields.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: When the application version (*version* from *org.mozilla.appinfo.appinfo*)
michael@0: changes, we record the new version on the day the change was seen. The new
michael@0: versions for a day are recorded in an array under the *version* property.
michael@0: 
michael@0: Notes
michael@0: ^^^^^
michael@0: 
michael@0: If the application isn't upgraded, this measurement will not be present.
michael@0: This means this measurement will not be present for most days if a user is
michael@0: on the release channel (since updates are typically released every 6 weeks).
michael@0: However, users on the Nightly and Aurora channels will likely have a lot
michael@0: of these entries since those builds are updated every day.
michael@0: 
michael@0: Values for this measurement are collected when performing the daily
michael@0: collection (typically occurs at upload time). As a result, it's possible
michael@0: the actual upgrade day may not be attributed to the proper day - the
michael@0: reported day may lag behind.
michael@0: 
michael@0: The app and platform versions and build IDs should be identical for most
michael@0: clients. If they are different, we are possibly looking at a *Frankenfox*.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "2013-03-27": {
michael@0:       "org.mozilla.appInfo.versions": {
michael@0:         "_v": 2,
michael@0:         "appVersion": [
michael@0:            "22.0.0"
michael@0:         ],
michael@0:         "appBuildID": [
michael@0:           "20130325031100"
michael@0:         ],
michael@0:         "platformVersion": [
michael@0:           "22.0.0"
michael@0:         ],
michael@0:         "platformBuildID": [
michael@0:           "20130325031100"
michael@0:         ]
michael@0:       }
michael@0:     }
michael@0: 
michael@0: org.mozilla.appSessions.current
michael@0: -------------------------------
michael@0: 
michael@0: This measurement contains information about the currently running XUL
michael@0: application's session.
michael@0: 
michael@0: Version 3
michael@0: ^^^^^^^^^
michael@0: 
michael@0: This measurement has the following properties:
michael@0: 
michael@0: startDay
michael@0:     Integer days since UNIX epoch when this session began.
michael@0: activeTicks
michael@0:     Integer count of *ticks* the session was active for. Gecko periodically
michael@0:     sends out a signal when the session is active. Session activity
michael@0:     involves keyboard or mouse interaction with the application. Each tick
michael@0:     represents a window of 5 seconds where there was interaction.
michael@0: totalTime
michael@0:     Integer seconds the session has been alive.
michael@0: main
michael@0:     Integer milliseconds it took for the Gecko process to start up.
michael@0: firstPaint
michael@0:     Integer milliseconds from process start to first paint.
michael@0: sessionRestored
michael@0:     Integer milliseconds from process start to session restore.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "org.mozilla.appSessions.current": {
michael@0:       "_v": 3,
michael@0:       "startDay": 15775,
michael@0:       "activeTicks": 4282,
michael@0:       "totalTime": 249422,
michael@0:       "main": 851,
michael@0:       "firstPaint": 3271,
michael@0:       "sessionRestored": 5998
michael@0:     }
michael@0: 
michael@0: org.mozilla.appSessions.previous
michael@0: --------------------------------
michael@0: 
michael@0: This measurement contains information about previous XUL application sessions.
michael@0: 
michael@0: Version 3
michael@0: ^^^^^^^^^
michael@0: 
michael@0: This measurement contains per-day lists of all the sessions started on that
michael@0: day. The following properties may be present:
michael@0: 
michael@0: cleanActiveTicks
michael@0:     Active ticks of sessions that were properly shut down.
michael@0: cleanTotalTime
michael@0:     Total number of seconds for sessions that were properly shut down.
michael@0: abortedActiveTicks
michael@0:     Active ticks of sessions that were not properly shut down.
michael@0: abortedTotalTime
michael@0:     Total number of seconds for sessions that were not properly shut down.
michael@0: main
michael@0:     Time in milliseconds from process start to main process initialization.
michael@0: firstPaint
michael@0:     Time in milliseconds from process start to first paint.
michael@0: sessionRestored
michael@0:     Time in milliseconds from process start to session restore.
michael@0: 
michael@0: Notes
michael@0: ^^^^^
michael@0: 
michael@0: Sessions are recorded on the date on which they began.
michael@0: 
michael@0: If a session was aborted/crashed, the total time may be less than the actual
michael@0: total time. This is because we don't always update total time during periods
michael@0: of inactivity and the abort/crash could occur after a long period of idle,
michael@0: before we've updated the total time.
michael@0: 
michael@0: The lengths of the arrays for {cleanActiveTicks, cleanTotalTime},
michael@0: {abortedActiveTicks, abortedTotalTime}, and {main, firstPaint, sessionRestored}
michael@0: should all be identical.
michael@0: 
michael@0: The length of the clean sessions plus the length of the aborted sessions should
michael@0: be equal to the length of the {main, firstPaint, sessionRestored} properties.
michael@0: 
michael@0: It is not possible to distinguish the main, firstPaint, and sessionRestored
michael@0: values from a clean vs aborted session: they are all lumped together.
michael@0: 
michael@0: For sessions spanning multiple UTC days, it's not possible to know which
michael@0: days the session was active for. It's possible a week long session only
michael@0: had activity for 2 days and there's no way for us to tell which days.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "org.mozilla.appSessions.previous": {
michael@0:       "_v": 3,
michael@0:       "cleanActiveTicks": [
michael@0:         78,
michael@0:         1785
michael@0:       ],
michael@0:       "cleanTotalTime": [
michael@0:         4472,
michael@0:         88908
michael@0:       ],
michael@0:       "main": [
michael@0:         32,
michael@0:         952
michael@0:       ],
michael@0:       "firstPaint": [
michael@0:         2755,
michael@0:         3497
michael@0:       ],
michael@0:       "sessionRestored": [
michael@0:         5149,
michael@0:         5520
michael@0:       ]
michael@0:     }
michael@0: 
michael@0: org.mozilla.crashes.crashes
michael@0: ---------------------------
michael@0: 
michael@0: This measurement contains a historical record of application crashes.
michael@0: 
michael@0: Version 2
michael@0: ^^^^^^^^^
michael@0: 
michael@0: The switch to version 2 coincides with the introduction of the
michael@0: :ref:`crashes_crashmanager`, which provides a more robust source of
michael@0: crash data.
michael@0: 
michael@0: This measurement will be reported on each day there was a crash. The
michael@0: following fields may be present in each record:
michael@0: 
michael@0: mainCrash
michael@0:    The number of main process crashes that occurred on the given day.
michael@0: 
michael@0: Yes, version 2 does not track submissions like version 1. It is very
michael@0: likely submissions will be re-added later.
michael@0: 
michael@0: Also absent from version 2 are plugin crashes and hangs. These will be
michael@0: re-added, likely in version 3.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: This measurement will be reported on each day there was a crash. The
michael@0: following properties are reported:
michael@0: 
michael@0: pending
michael@0:     The number of crash reports that haven't been submitted.
michael@0: submitted
michael@0:     The number of crash reports that were submitted.
michael@0: 
michael@0: Notes
michael@0: ^^^^^
michael@0: 
michael@0: Main process crashes are typically submitted immediately after they
michael@0: occur (by checking a box in the crash reporter, which should appear
michael@0: automatically after a crash). If the crash reporter submits the crash
michael@0: successfully, we get a submitted crash. Else, we leave it as pending.
michael@0: 
michael@0: A pending crash does not mean it will eventually be submitted.
michael@0: 
michael@0: Pending crash reports can be submitted post-crash by going to
michael@0: about:crashes.
michael@0: 
michael@0: If a pending crash is submitted via about:crashes, the submitted count
michael@0: increments but the pending count does not decrement. This is because FHR
michael@0: does not know which pending crash was just submitted and therefore it does
michael@0: not know which day's pending crash to decrement.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "org.mozilla.crashes.crashes": {
michael@0:       "_v": 1,
michael@0:       "pending": 1,
michael@0:       "submitted": 2
michael@0:     },
michael@0:     "org.mozilla.crashes.crashes": {
michael@0:       "_v": 2,
michael@0:       "mainCrash": 2
michael@0:     }
michael@0: 
michael@0: org.mozilla.healthreport.submissions
michael@0: ------------------------------------
michael@0: 
michael@0: This measurement contains a history of FHR's own data submission activity.
michael@0: It was added in Firefox 23 in early May 2013.
michael@0: 
michael@0: Version 2
michael@0: ^^^^^^^^^
michael@0: 
michael@0: This is the same as version 1 except an additional field has been added.
michael@0: 
michael@0: uploadAlreadyInProgress
michael@0:    A request for upload was initiated while another upload was in progress.
michael@0:    This should not occur in well-behaving clients. It (along with a lock
michael@0:    preventing simultaneous upload) was added to ensure this never occurs.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: Daily counts of upload events are recorded.
michael@0: 
michael@0: firstDocumentUploadAttempt
michael@0:     An attempt was made to upload the client's first document to the server.
michael@0:     These are uploads where the client is not aware of a previous document ID
michael@0:     on the server. Unless the client had disabled upload, there should be at
michael@0:     most one of these in the history of the client.
michael@0: 
michael@0: continuationUploadAttempt
michael@0:     An attempt was made to upload a document that replaces an existing document
michael@0:     on the server. Most upload attempts should be attributed to this as opposed
michael@0:     to *firstDocumentUploadAttempt*.
michael@0: 
michael@0: uploadSuccess
michael@0:     The upload attempt recorded by *firstDocumentUploadAttempt* or
michael@0:     *continuationUploadAttempt* was successful.
michael@0: 
michael@0: uploadTransportFailure
michael@0:     An upload attempt failed due to transport failure (network unavailable,
michael@0:     etc).
michael@0: 
michael@0: uploadServerFailure
michael@0:     An upload attempt failed due to a server-reported failure. Ideally these
michael@0:     are failures reported by the FHR server itself. However, intermediate
michael@0:     proxies, firewalls, etc may trigger this depending on how things are
michael@0:     configured.
michael@0: 
michael@0: uploadClientFailure
michael@0:     An upload attempt failued due to an error/exception in the client.
michael@0:     This almost certainly points to a bug in the client.
michael@0: 
michael@0: The result for an upload attempt is always attributed to the same day as
michael@0: the attempt, even if the result occurred on a different day from the attempt.
michael@0: Therefore, the sum of the result counts should equal the result of the attempt
michael@0: counts.
michael@0: 
michael@0: org.mozilla.places.places
michael@0: -------------------------
michael@0: 
michael@0: This measurement contains information about the Places database (where Firefox
michael@0: stores its history and bookmarks).
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: Daily counts of items in the database are reported in the following properties:
michael@0: 
michael@0: bookmarks
michael@0:     Integer count of bookmarks present.
michael@0: pages
michael@0:     Integer count of pages in the history database.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "org.mozilla.places.places": {
michael@0:       "_v": 1,
michael@0:       "bookmarks": 388,
michael@0:       "pages": 94870
michael@0:     }
michael@0: 
michael@0: org.mozilla.profile.age
michael@0: -----------------------
michael@0: 
michael@0: This measurement contains information about the current profile's age.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: A single *profileCreation* property is present. It defines the integer
michael@0: days since UNIX epoch that the current profile was created.
michael@0: 
michael@0: Notes
michael@0: ^^^^^
michael@0: 
michael@0: It is somewhat difficult to obtain a reliable *profile born date* due to a
michael@0: number of factors.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "org.mozilla.profile.age": {
michael@0:       "_v": 1,
michael@0:       "profileCreation": 15176
michael@0:     }
michael@0: 
michael@0: org.mozilla.searches.counts
michael@0: ---------------------------
michael@0: 
michael@0: This measurement contains information about searches performed in the
michael@0: application.
michael@0: 
michael@0: Version 2
michael@0: ^^^^^^^^^
michael@0: 
michael@0: This behaves like version 1 except we added all search engines that
michael@0: Mozilla has a partner agreement with. Like version 1, we concatenate
michael@0: a search engine ID with a search origin.
michael@0: 
michael@0: Another difference with version 2 is we should no longer misattribute
michael@0: a search to the *other* bucket if the search engine name is localized.
michael@0: 
michael@0: The set of search engine providers is:
michael@0: 
michael@0: * amazon-co-uk
michael@0: * amazon-de
michael@0: * amazon-en-GB
michael@0: * amazon-france
michael@0: * amazon-it
michael@0: * amazon-jp
michael@0: * amazondotcn
michael@0: * amazondotcom
michael@0: * amazondotcom-de
michael@0: * aol-en-GB
michael@0: * aol-web-search
michael@0: * bing
michael@0: * eBay
michael@0: * eBay-de
michael@0: * eBay-en-GB
michael@0: * eBay-es
michael@0: * eBay-fi
michael@0: * eBay-france
michael@0: * eBay-hu
michael@0: * eBay-in
michael@0: * eBay-it
michael@0: * google
michael@0: * google-jp
michael@0: * google-ku
michael@0: * google-maps-zh-TW
michael@0: * mailru
michael@0: * mercadolibre-ar
michael@0: * mercadolibre-cl
michael@0: * mercadolibre-mx
michael@0: * seznam-cz
michael@0: * twitter
michael@0: * twitter-de
michael@0: * twitter-ja
michael@0: * yahoo
michael@0: * yahoo-NO
michael@0: * yahoo-answer-zh-TW
michael@0: * yahoo-ar
michael@0: * yahoo-bid-zh-TW
michael@0: * yahoo-br
michael@0: * yahoo-ch
michael@0: * yahoo-cl
michael@0: * yahoo-de
michael@0: * yahoo-en-GB
michael@0: * yahoo-es
michael@0: * yahoo-fi
michael@0: * yahoo-france
michael@0: * yahoo-fy-NL
michael@0: * yahoo-id
michael@0: * yahoo-in
michael@0: * yahoo-it
michael@0: * yahoo-jp
michael@0: * yahoo-jp-auctions
michael@0: * yahoo-mx
michael@0: * yahoo-sv-SE
michael@0: * yahoo-zh-TW
michael@0: * yandex
michael@0: * yandex-ru
michael@0: * yandex-slovari
michael@0: * yandex-tr
michael@0: * yandex.by
michael@0: * yandex.ru-be
michael@0: 
michael@0: And of course, *other*.
michael@0: 
michael@0: The sources for searches remain:
michael@0: 
michael@0: * abouthome
michael@0: * contextmenu
michael@0: * searchbar
michael@0: * urlbar
michael@0: 
michael@0: The measurement will only be populated with providers and sources that
michael@0: occurred that day.
michael@0: 
michael@0: If a user switches locales, searches from default providers on the older
michael@0: locale will still be supported. However, if that same search engine is
michael@0: added by the user to the new build and is *not* a default search engine
michael@0: provider, its searches will be attributed to the *other* bucket.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: We record counts of performed searches grouped by search engine and search
michael@0: origin. Only search engines with which Mozilla has a business relationship
michael@0: are explicitly counted. All other search engines are grouped into an
michael@0: *other* bucket.
michael@0: 
michael@0: The following search engines are explicitly counted:
michael@0: 
michael@0: * Amazon.com
michael@0: * Bing
michael@0: * Google
michael@0: * Yahoo
michael@0: * Other
michael@0: 
michael@0: The following search origins are distinguished:
michael@0: 
michael@0: about:home
michael@0:     Searches initiated from the search text box on about:home.
michael@0: context menu
michael@0:     Searches initiated from the context menu (highlight text, right click,
michael@0:     and select "search for...")
michael@0: search bar
michael@0:     Searches initiated from the search bar (the text field next to the
michael@0:     Awesomebar)
michael@0: url bar
michael@0:     Searches initiated from the awesomebar/url bar.
michael@0: 
michael@0: Due to the localization of search engine names, non en-US locales may wrongly
michael@0: attribute searches to the *other* bucket. This is fixed in version 2.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "org.mozilla.searches.counts": {
michael@0:       "_v": 1,
michael@0:       "google.searchbar": 3,
michael@0:       "google.urlbar": 7
michael@0:     },
michael@0: 
michael@0: org.mozilla.searches.engines
michael@0: ----------------------------
michael@0: 
michael@0: This measurement contains information about search engines.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: This version debuted with Firefox 31 on desktop. It contains the
michael@0: following properties:
michael@0: 
michael@0: default
michael@0:    Daily string identifier or name of the default search engine provider.
michael@0: 
michael@0:    This field will only be collected if Telemetry is enabled. If
michael@0:    Telemetry is enabled and then later disabled, this field may
michael@0:    disappear from future days in the payload.
michael@0: 
michael@0:    The special value ``NONE`` could occur if there is no default search
michael@0:    engine.
michael@0: 
michael@0:    The special value ``UNDEFINED`` could occur if a default search
michael@0:    engine exists but its identifier could not be determined.
michael@0: 
michael@0:    This field's contents are
michael@0:    ``Services.search.defaultEngine.identifier`` (if defined) or
michael@0:    ``"other-"`` + ``Services.search.defaultEngine.name`` if not.
michael@0:    In other words, search engines without an ``.identifier``
michael@0:    are prefixed with ``other-``.
michael@0: 
michael@0: org.mozilla.sync.sync
michael@0: ---------------------
michael@0: 
michael@0: This daily measurement contains information about the Sync service.
michael@0: 
michael@0: Values should be recorded for every day FHR measurements occurred.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: This version debuted with Firefox 30 on desktop. It contains the following
michael@0: properties:
michael@0: 
michael@0: enabled
michael@0:    Daily numeric indicating whether Sync is configured and enabled. 1 if so,
michael@0:    0 otherwise.
michael@0: 
michael@0: preferredProtocol
michael@0:    String version of the maximum Sync protocol version the client supports.
michael@0:    This will be ``1.1`` for for legacy Sync and ``1.5`` for clients that
michael@0:    speak the Firefox Accounts protocol.
michael@0: 
michael@0: actualProtocol
michael@0:    The actual Sync protocol version the client is configured to use.
michael@0: 
michael@0:    This will be ``1.1`` if the client is configured with the legacy Sync
michael@0:    service or if the client only supports ``1.1``.
michael@0: 
michael@0:    It will be ``1.5`` if the client supports ``1.5`` and either a) the
michael@0:    client is not configured b) the client is using Firefox Accounts Sync.
michael@0: 
michael@0: syncStart
michael@0:    Count of sync operations performed.
michael@0: 
michael@0: syncSuccess
michael@0:    Count of sync operations that completed successfully.
michael@0: 
michael@0: syncError
michael@0:    Count of sync operations that did not complete successfully.
michael@0: 
michael@0:    This is a measure of overall sync success. This does *not* reflect
michael@0:    recoverable errors (such as record conflict) that can occur during
michael@0:    sync. This is thus a rough proxy of whether the sync service is
michael@0:    operating without error.
michael@0: 
michael@0: org.mozilla.sync.devices
michael@0: ------------------------
michael@0: 
michael@0: This daily measurement contains information about the device type composition
michael@0: for the configured Sync account.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: Version 1 was introduced with Firefox 30.
michael@0: 
michael@0: Field names are dynamic according to the client-reported device types from
michael@0: Sync records. All fields are daily last seen integer values corresponding to
michael@0: the number of devices of that type.
michael@0: 
michael@0: Common values include:
michael@0: 
michael@0: desktop
michael@0:    Corresponds to a Firefox desktop client.
michael@0: 
michael@0: mobile
michael@0:    Corresponds to a Fennec client.
michael@0: 
michael@0: org.mozilla.sysinfo.sysinfo
michael@0: ---------------------------
michael@0: 
michael@0: This measurement contains basic information about the system the application
michael@0: is running on.
michael@0: 
michael@0: Version 2
michael@0: ^^^^^^^^^
michael@0: 
michael@0: This version debuted with Firefox 29 on desktop.
michael@0: 
michael@0: A single property was introduced.
michael@0: 
michael@0: isWow64
michael@0:    If present, this property indicates whether the machine supports WoW64.
michael@0:    This property can be used to identify whether the host machine is 64-bit.
michael@0: 
michael@0:    This property is only present on Windows machines. It is the preferred way
michael@0:    to identify 32- vs 64-bit support in that environment.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: The following properties may be available:
michael@0: 
michael@0: cpuCount
michael@0:     Integer number of CPUs/cores in the machine.
michael@0: memoryMB
michael@0:     Integer megabytes of memory in the machine.
michael@0: manufacturer
michael@0:     The manufacturer of the device.
michael@0: device
michael@0:     The name of the device (like model number).
michael@0: hardware
michael@0:     Unknown.
michael@0: name
michael@0:     OS name.
michael@0: version
michael@0:     OS version.
michael@0: architecture
michael@0:     OS architecture that the application is built for. This is not the
michael@0:     actual system architecture.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "org.mozilla.sysinfo.sysinfo": {
michael@0:       "_v": 1,
michael@0:       "cpuCount": 8,
michael@0:       "memoryMB": 8192,
michael@0:       "architecture": "x86-64",
michael@0:       "name": "Darwin",
michael@0:       "version": "12.2.0"
michael@0:     }
michael@0: 
michael@0: 
michael@0: 
michael@0: org.mozilla.experiments.info
michael@0: ----------------------------------
michael@0: 
michael@0: Daily measurement reporting information about the Telemetry Experiments service.
michael@0: 
michael@0: Version 1
michael@0: ^^^^^^^^^
michael@0: 
michael@0: Property:
michael@0: 
michael@0: lastActive
michael@0:     ID of the final Telemetry Experiment that is active on a given day, if any.
michael@0: 
michael@0: 
michael@0: Version 2
michael@0: ^^^^^^^^^
michael@0: 
michael@0: Adds an additional optional property:
michael@0: 
michael@0: lastActiveBranch
michael@0:     If the experiment uses branches, the branch identifier string.
michael@0: 
michael@0: Example
michael@0: ^^^^^^^
michael@0: 
michael@0: ::
michael@0: 
michael@0:     "org.mozilla.experiments.info": {
michael@0:       "_v": 2,
michael@0:       "lastActive": "some.experiment.id",
michael@0:       "lastActiveBranch": "control"
michael@0:     }
michael@0: