services/healthreport/docs/dataformat.rst@4ab42b5ab56c
services/healthreport/docs/dataformat.rst
Wed, 31 Dec 2014 07:53:36 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Wed, 31 Dec 2014 07:53:36 +0100
- branch
- TOR_BUG_3246
- changeset 5
- 4ab42b5ab56c
- permissions
- -rw-r--r--
Correct small whitespace inconsistency, lost while renaming variables.
1 .. _healthreport_dataformat:
3 ==============
4 Payload Format
5 ==============
7 Currently, the Firefox Health Report is submitted as a compressed JSON
8 document. The root JSON element is an object. A *version* field defines
9 the version of the payload which in turn defines the expected contents
10 the object.
12 As of 2013-07-03, desktop submits Version 2, and Firefox for Android submits
13 Version 3 payloads.
15 Version 3
16 =========
18 Version 3 is a complete rebuild of the document format. Events are tracked in
19 an "environment". Environments are computed from a large swath of local data
20 (e.g., add-ons, CPU count, versions), and a new environment comes into being
21 when one of its attributes changes.
23 Client documents, then, will include descriptions of many environments, and
24 measurements will be attributed to one particular environment.
26 A map of environments is present at the top level of the document, with the
27 current named "current" in the map. Each environment has a hash identifier and
28 a set of attributes. The current environment is completely described, and has
29 its hash present in a "hash" attribute. All other environments are represented
30 as a tree diff from the current environment, with their hash as the key in the
31 "environments" object.
33 A removed add-on has the value 'null'.
35 There is no "last" data at present.
37 Daily data is hierarchical: by day, then by environment, and then by
38 measurement, and is present in "data", just as in v2.
40 Leading by example::
42 {
43 "lastPingDate": "2013-06-29",
44 "thisPingDate": "2013-07-03",
45 "version": 3,
46 "environments": {
47 "current": {
48 "org.mozilla.sysinfo.sysinfo": {
49 "memoryMB": 1567,
50 "cpuCount": 4,
51 "architecture": "armeabi-v7a",
52 "_v": 1,
53 "version": "4.1.2",
54 "name": "Android"
55 },
56 "org.mozilla.profile.age": {
57 "_v": 1,
58 "profileCreation": 15827
59 },
60 "org.mozilla.addons.active": {
61 "QuitNow@TWiGSoftware.com": {
62 "appDisabled": false,
63 "userDisabled": false,
64 "scope": 1,
65 "updateDay": 15885,
66 "foreignInstall": false,
67 "hasBinaryComponents": false,
68 "blocklistState": 0,
69 "type": "extension",
70 "installDay": 15885,
71 "version": "1.18.02"
72 },
73 "{dbbf9331-b713-6eda-1006-205efead09dc}": {
74 "appDisabled": false,
75 "userDisabled": "askToActivate",
76 "scope": 8,
77 "updateDay": 15779,
78 "foreignInstall": true,
79 "blocklistState": 0,
80 "type": "plugin",
81 "installDay": 15779,
82 "version": "11.1 r115"
83 },
84 "desktopbydefault@bnicholson.mozilla.org": {
85 "appDisabled": false,
86 "userDisabled": true,
87 "scope": 1,
88 "updateDay": 15870,
89 "foreignInstall": false,
90 "hasBinaryComponents": false,
91 "blocklistState": 0,
92 "type": "extension",
93 "installDay": 15870,
94 "version": "1.1"
95 },
96 "{6e092a7f-ba58-4abb-88c1-1a4e50b217e4}": {
97 "appDisabled": false,
98 "userDisabled": false,
99 "scope": 1,
100 "updateDay": 15828,
101 "foreignInstall": false,
102 "hasBinaryComponents": false,
103 "blocklistState": 0,
104 "type": "extension",
105 "installDay": 15828,
106 "version": "1.1.0"
107 },
108 "{46551EC9-40F0-4e47-8E18-8E5CF550CFB8}": {
109 "appDisabled": false,
110 "userDisabled": true,
111 "scope": 1,
112 "updateDay": 15879,
113 "foreignInstall": false,
114 "hasBinaryComponents": false,
115 "blocklistState": 0,
116 "type": "extension",
117 "installDay": 15879,
118 "version": "1.3.2"
119 },
120 "_v": 1
121 },
122 "org.mozilla.appInfo.appinfo": {
123 "_v": 3,
124 "appLocale": "en_us",
125 "osLocale": "en_us",
126 "distribution": "",
127 "acceptLangIsUserSet": 0,
128 "isTelemetryEnabled": 1,
129 "isBlocklistEnabled": 1
130 },
131 "geckoAppInfo": {
132 "updateChannel": "nightly",
133 "id": "{aa3c5121-dab2-40e2-81ca-7ea25febc110}",
134 "os": "Android",
135 "platformBuildID": "20130703031323",
136 "platformVersion": "25.0a1",
137 "vendor": "Mozilla",
138 "name": "fennec",
139 "xpcomabi": "arm-eabi-gcc3",
140 "appBuildID": "20130703031323",
141 "_v": 1,
142 "version": "25.0a1"
143 },
144 "hash": "tB4Pnnep9yTxnMDymc3dAB2RRB0=",
145 "org.mozilla.addons.counts": {
146 "extension": 4,
147 "plugin": 1,
148 "_v": 1,
149 "theme": 0
150 }
151 },
152 "k2O3hlreMeS7L1qtxeMsYWxgWWQ=": {
153 "geckoAppInfo": {
154 "platformBuildID": "20130630031138",
155 "appBuildID": "20130630031138",
156 "_v": 1
157 },
158 "org.mozilla.appInfo.appinfo": {
159 "_v": 2,
160 }
161 },
162 "1+KN9TutMpzdl4TJEl+aCxK+xcw=": {
163 "geckoAppInfo": {
164 "platformBuildID": "20130626031100",
165 "appBuildID": "20130626031100",
166 "_v": 1
167 },
168 "org.mozilla.addons.active": {
169 "QuitNow@TWiGSoftware.com": null,
170 "{dbbf9331-b713-6eda-1006-205efead09dc}": null,
171 "desktopbydefault@bnicholson.mozilla.org": null,
172 "{6e092a7f-ba58-4abb-88c1-1a4e50b217e4}": null,
173 "{46551EC9-40F0-4e47-8E18-8E5CF550CFB8}": null,
174 "_v": 1
175 },
176 "org.mozilla.addons.counts": {
177 "extension": 0,
178 "plugin": 0,
179 "_v": 1
180 }
181 }
182 },
183 "data": {
184 "last": {},
185 "days": {
186 "2013-07-03": {
187 "tB4Pnnep9yTxnMDymc3dAB2RRB0=": {
188 "org.mozilla.appSessions": {
189 "normal": [
190 {
191 "r": "P",
192 "d": 2,
193 "sj": 653
194 },
195 {
196 "r": "P",
197 "d": 22
198 },
199 {
200 "r": "P",
201 "d": 5
202 },
203 {
204 "r": "P",
205 "d": 0
206 },
207 {
208 "r": "P",
209 "sg": 3560,
210 "d": 171,
211 "sj": 518
212 },
213 {
214 "r": "P",
215 "d": 16
216 },
217 {
218 "r": "P",
219 "d": 1079
220 }
221 ],
222 "_v": "4"
223 }
224 },
225 "k2O3hlreMeS7L1qtxeMsYWxgWWQ=": {
226 "org.mozilla.appSessions": {
227 "normal": [
228 {
229 "r": "P",
230 "d": 27
231 },
232 {
233 "r": "P",
234 "d": 19
235 },
236 {
237 "r": "P",
238 "d": 55
239 }
240 ],
241 "_v": "4"
242 },
243 "org.mozilla.searches.counts": {
244 "bartext": {
245 "google": 1
246 },
247 "_v": "4"
248 },
249 "org.mozilla.experiment": {
250 "lastActive": "some.experiment.id"
251 "_v": "1"
252 }
253 }
254 }
255 }
256 }
257 }
259 App sessions in Version 3
260 -------------------------
262 Sessions are divided into "normal" and "abnormal". Session objects are stored as discrete JSON::
264 "org.mozilla.appSessions": {
265 _v: 4,
266 "normal": [
267 {"r":"P", "d": 123},
268 ],
269 "abnormal": [
270 {"r":"A", "oom": true, "stopped": false}
271 ]
272 }
274 Keys are:
276 "r"
277 reason. Values are "P" (activity paused), "A" (abnormal termination).
278 "d"
279 duration. Value in seconds.
280 "sg"
281 Gecko startup time (msec). Present if this is a clean launch. This
282 corresponds to the telemetry timer *FENNEC_STARTUP_TIME_GECKOREADY*.
283 "sj"
284 Java activity init time (msec). Present if this is a clean launch. This
285 corresponds to the telemetry timer *FENNEC_STARTUP_TIME_JAVAUI*,
286 and includes initialization tasks beyond initial
287 *onWindowFocusChanged*.
289 Abnormal terminations will be missing a duration and will feature these keys:
291 "oom"
292 was the session killed by an OOM exception?
293 "stopped"
294 was the session stopped gently?
296 Version 3.1
297 -----------
299 As of Firefox 27, *appinfo* is now bumped to v3, including *osLocale*,
300 *appLocale* (currently always the same as *osLocale*), *distribution* (a string
301 containing the distribution ID and version, separated by a colon), and
302 *acceptLangIsUserSet*, an integer-boolean that describes whether the user set
303 an *intl.accept_languages* preference.
305 The search counts measurement is now at version 5, which indicates that
306 non-partner searches are recorded. You'll see identifiers like "other-Foo Bar"
307 rather than "other".
309 Other notable differences from Version 2
310 ----------------------------------------
312 * There is no default browser indicator on Android.
313 * Add-ons include a *blocklistState* attribute, as returned by AddonManager.
314 * Searches are now version 4, and are hierarchical: how the search was started
315 (bartext, barkeyword, barsuggest), and then counts per provider.
317 Version 2
318 =========
320 Version 2 is the same as version 1 with the exception that it has an additional
321 top-level field, *geckoAppInfo*, which contains basic application info.
323 geckoAppInfo
324 ------------
326 This field is an object that is a simple map of string keys and values
327 describing basic application metadata. It is very similar to the *appinfo*
328 measurement in the *last* section. The difference is this field is almost
329 certainly guaranteed to exist whereas the one in the data part of the
330 payload may be omitted in certain scenarios (such as catastrophic client
331 error).
333 Its keys are as follows:
335 appBuildID
336 The build ID/date of the application. e.g. "20130314113542".
338 version
339 The value of nsXREAppData.version. This is the application's version. e.g.
340 "21.0.0".
342 vendor
343 The value of nsXREAppData.vendor. Can be empty an empty string. For
344 official Mozilla builds, this will be "Mozilla".
346 name
347 The value of nsXREAppData.name. For official Firefox builds, this
348 will be "Firefox".
350 id
351 The value of nsXREAppData.ID.
353 platformVersion
354 The version of the Gecko platform (as opposed to the app version). For
355 Firefox, this is almost certainly equivalent to the *version* field.
357 platformBuildID
358 The build ID/date of the Gecko platfor (as opposed to the app version).
359 This is commonly equivalent to *appBuildID*.
361 os
362 The name of the operating system the application is running on.
364 xpcomabi
365 The binary architecture of the build.
367 updateChannel
368 The name of the channel used for application updates. Official Mozilla
369 builds have one of the values {release, beta, aurora, nightly}. Local and
370 test builds have *default* as the channel.
372 Version 1
373 =========
375 Top-level Properties
376 --------------------
378 The main JSON object contains the following properties:
380 lastPingDate
381 UTC date of the last upload. If this is the first upload from this client,
382 this will not be present.
384 thisPingDate
385 UTC date when this payload was constructed.
387 version
388 Integer version of this payload format. Currently only 1 is defined.
390 clientID
391 An identifier that identifies the client that is submitting data.
393 This property may not be present in older clients.
395 See :ref:`healthreport_identifiers` for more info on identifiers.
397 clientIDVersion
398 Integer version associated with the generation semantics for the
399 ``clientID``.
401 If the value is ``1``, ``clientID`` is a randomly-generated UUID.
403 This property may not be present in older clients.
405 data
406 Object holding data constituting health report.
408 Data Properties
409 ---------------
411 The bulk of the health report is contained within the *data* object. This
412 object has the following keys:
414 days
415 Object mapping UTC days to measurements from that day. Keys are in the
416 *YYYY-MM-DD* format. e.g. "2013-03-14"
418 last
419 Object mapping measurement names to their values.
422 The value of *days* and *last* are objects mapping measurement names to that
423 measurement's values. The values are always objects. Each object contains
424 a *_v* property. This property defines the version of this measurement.
425 Additional non-underscore-prefixed properties are defined by the measurement
426 itself (see sections below).
428 Example
429 -------
431 Here is an example JSON document for version 1::
433 {
434 "version": 1,
435 "thisPingDate": "2013-03-11",
436 "lastPingDate": "2013-03-10",
437 "data": {
438 "last": {
439 "org.mozilla.addons.active": {
440 "masspasswordreset@johnathan.nightingale": {
441 "userDisabled": false,
442 "appDisabled": false,
443 "version": "1.05",
444 "type": "extension",
445 "scope": 1,
446 "foreignInstall": false,
447 "hasBinaryComponents": false,
448 "installDay": 14973,
449 "updateDay": 15317
450 },
451 "places-maintenance@bonardo.net": {
452 "userDisabled": false,
453 "appDisabled": false,
454 "version": "1.3",
455 "type": "extension",
456 "scope": 1,
457 "foreignInstall": false,
458 "hasBinaryComponents": false,
459 "installDay": 15268,
460 "updateDay": 15379
461 },
462 "_v": 1
463 },
464 "org.mozilla.appInfo.appinfo": {
465 "_v": 1,
466 "appBuildID": "20130309030841",
467 "distributionID": "",
468 "distributionVersion": "",
469 "hotfixVersion": "",
470 "id": "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}",
471 "locale": "en-US",
472 "name": "Firefox",
473 "os": "Darwin",
474 "platformBuildID": "20130309030841",
475 "platformVersion": "22.0a1",
476 "updateChannel": "nightly",
477 "vendor": "Mozilla",
478 "version": "22.0a1",
479 "xpcomabi": "x86_64-gcc3"
480 },
481 "org.mozilla.profile.age": {
482 "_v": 1,
483 "profileCreation": 12444
484 },
485 "org.mozilla.appSessions.current": {
486 "_v": 3,
487 "startDay": 15773,
488 "activeTicks": 522,
489 "totalTime": 70858,
490 "main": 1245,
491 "firstPaint": 2695,
492 "sessionRestored": 3436
493 },
494 "org.mozilla.sysinfo.sysinfo": {
495 "_v": 1,
496 "cpuCount": 8,
497 "memoryMB": 16384,
498 "architecture": "x86-64",
499 "name": "Darwin",
500 "version": "12.2.1"
501 }
502 },
503 "days": {
504 "2013-03-11": {
505 "org.mozilla.addons.counts": {
506 "_v": 1,
507 "extension": 15,
508 "plugin": 12,
509 "theme": 1
510 },
511 "org.mozilla.places.places": {
512 "_v": 1,
513 "bookmarks": 757,
514 "pages": 104858
515 },
516 "org.mozilla.appInfo.appinfo": {
517 "_v": 1,
518 "isDefaultBrowser": 1
519 }
520 },
521 "2013-03-10": {
522 "org.mozilla.addons.counts": {
523 "_v": 1,
524 "extension": 15,
525 "plugin": 12,
526 "theme": 1
527 },
528 "org.mozilla.places.places": {
529 "_v": 1,
530 "bookmarks": 757,
531 "pages": 104857
532 },
533 "org.mozilla.searches.counts": {
534 "_v": 1,
535 "google.urlbar": 4
536 },
537 "org.mozilla.appInfo.appinfo": {
538 "_v": 1,
539 "isDefaultBrowser": 1
540 }
541 }
542 }
543 }
544 }
546 Measurements
547 ============
549 The bulk of payloads consists of measurement data. An individual measurement
550 is merely a collection of related values e.g. *statistics about the Places
551 database* or *system information*.
553 Each measurement has an integer version number attached. When the fields in
554 a measurement or the semantics of data within that measurement change, the
555 version number is incremented.
557 All measurements are defined alphabetically in the sections below.
559 org.mozilla.addons.addons
560 -------------------------
562 This measurement contains information about the currently-installed add-ons.
564 Version 2
565 ^^^^^^^^^
567 This version adds the human-readable fields *name* and *description*, both
568 coming directly from the Addon instance as most properties in version 1.
569 Also, all plugin details are now in org.mozilla.addons.plugins.
571 Version 1
572 ^^^^^^^^^
574 The measurement object is a mapping of add-on IDs to objects containing
575 add-on metadata.
577 Each add-on contains the following properties:
579 * userDisabled
580 * appDisabled
581 * version
582 * type
583 * scope
584 * foreignInstall
585 * hasBinaryComponents
586 * installDay
587 * updateDay
589 With the exception of *installDay* and *updateDay*, all these properties
590 come direct from the Addon instance. See https://developer.mozilla.org/en-US/docs/Addons/Add-on_Manager/Addon.
591 *installDay* and *updateDay* are the number of days since UNIX epoch of
592 the add-ons *installDate* and *updateDate* properties, respectively.
594 Notes
595 ^^^^^
597 Add-ons that have opted out of AMO updates via the
598 *extensions._id_.getAddons.cache.enabled* preference are, since Bug 868306
599 (Firefox 24), included in the list of submitted add-ons.
601 Example
602 ^^^^^^^
603 ::
605 "org.mozilla.addons.addons": {
606 "_v": 2,
607 "{d10d0bf8-f5b5-c8b4-a8b2-2b9879e08c5d}": {
608 "userDisabled": false,
609 "appDisabled": false,
610 "name": "Adblock Plus",
611 "version": "2.4.1",
612 "type": "extension",
613 "scope": 1,
614 "description": "Ads were yesterday!",
615 "foreignInstall": false,
616 "hasBinaryComponents": false,
617 "installDay": 16093,
618 "updateDay": 16093
619 },
620 "{e4a8a97b-f2ed-450b-b12d-ee082ba24781}": {
621 "userDisabled": true,
622 "appDisabled": false,
623 "name": "Greasemonkey",
624 "version": "1.14",
625 "type": "extension",
626 "scope": 1,
627 "description": "A User Script Manager for Firefox",
628 "foreignInstall": false,
629 "hasBinaryComponents": false,
630 "installDay": 16093,
631 "updateDay": 16093
632 }
633 }
635 org.mozilla.addons.plugins
636 -------------------------
638 This measurement contains information about the currently-installed plugins.
640 Version 1
641 ^^^^^^^^^
643 The measurement object is a mapping of plugin IDs to objects containing
644 plugin metadata.
646 The plugin ID is constructed of the plugins filename, name, version and
647 description. Every plugin has at least a filename and a name.
649 Each plugin contains the following properties:
651 * name
652 * version
653 * description
654 * blocklisted
655 * disabled
656 * clicktoplay
657 * mimeTypes
658 * updateDay
660 With the exception of *updateDay* and *mimeTypes*, all these properties come
661 directly from ``nsIPluginTag`` via ``nsIPluginHost``.
662 *updateDay* is the number of days since UNIX epoch of the plugins last modified
663 time.
664 *mimeTypes* is the list of mimetypes the plugin supports, see
665 ``nsIPluginTag.getMimeTypes()`.
667 Example
668 ^^^^^^^
670 ::
672 "org.mozilla.addons.plugins": {
673 "_v": 1,
674 "Flash Player.plugin:Shockwave Flash:12.0.0.38:Shockwave Flash 12.0 r0": {
675 "mimeTypes": [
676 "application/x-shockwave-flash",
677 "application/futuresplash"
678 ],
679 "name": "Shockwave Flash",
680 "version": "12.0.0.38",
681 "description": "Shockwave Flash 12.0 r0",
682 "blocklisted": false,
683 "disabled": false,
684 "clicktoplay": false
685 },
686 "Default Browser.plugin:Default Browser Helper:537:Provides information about the default web browser": {
687 "mimeTypes": [
688 "application/apple-default-browser"
689 ],
690 "name": "Default Browser Helper",
691 "version": "537",
692 "description": "Provides information about the default web browser",
693 "blocklisted": false,
694 "disabled": true,
695 "clicktoplay": false
696 }
697 }
699 org.mozilla.addons.counts
700 -------------------------
702 This measurement contains information about historical add-on counts.
704 Version 1
705 ^^^^^^^^^
707 The measurement object consists of counts of different add-on types. The
708 properties are:
710 extension
711 Integer count of installed extensions.
712 plugin
713 Integer count of installed plugins.
714 theme
715 Integer count of installed themes.
716 lwtheme
717 Integer count of installed lightweigh themes.
719 Notes
720 ^^^^^
722 Add-ons opted out of AMO updates are included in the counts. This differs from
723 the behavior of the active add-ons measurement.
725 If no add-ons of a particular type are installed, the property for that type
726 will not be present (as opposed to an explicit property with value of 0).
728 Example
729 ^^^^^^^
731 ::
733 "2013-03-14": {
734 "org.mozilla.addons.counts": {
735 "_v": 1,
736 "extension": 21,
737 "plugin": 4,
738 "theme": 1
739 }
740 }
744 org.mozilla.appInfo.appinfo
745 ---------------------------
747 This measurement contains basic XUL application and Gecko platform
748 information. It is reported in the *last* section.
750 Version 2
751 ^^^^^^^^^
753 In addition to fields present in version 1, this version has the following
754 fields appearing in the *days* section:
756 isBlocklistEnabled
757 Whether the blocklist ping is enabled. This is an integer, 0 or 1.
758 This does not indicate whether the blocklist ping was sent but merely
759 whether the application will try to send the blocklist ping.
761 isTelemetryEnabled
762 Whether Telemetry is enabled. This is an integer, 0 or 1.
764 Version 1
765 ^^^^^^^^^
767 The measurement object contains mostly string values describing the
768 current application and build. The properties are:
770 * vendor
771 * name
772 * id
773 * version
774 * appBuildID
775 * platformVersion
776 * platformBuildID
777 * os
778 * xpcomabi
779 * updateChannel
780 * distributionID
781 * distributionVersion
782 * hotfixVersion
783 * locale
784 * isDefaultBrowser
786 Notes
787 ^^^^^
789 All of the properties appear in the *last* section except for
790 *isDefaultBrowser*, which appears under *days*.
792 Example
793 ^^^^^^^
795 This example comes from an official OS X Nightly build::
797 "org.mozilla.appInfo.appinfo": {
798 "_v": 1,
799 "appBuildID": "20130311030946",
800 "distributionID": "",
801 "distributionVersion": "",
802 "hotfixVersion": "",
803 "id": "{ec8030f7-c20a-464f-9b0e-13a3a9e97384}",
804 "locale": "en-US",
805 "name": "Firefox",
806 "os": "Darwin",
807 "platformBuildID": "20130311030946",
808 "platformVersion": "22.0a1",
809 "updateChannel": "nightly",
810 "vendor": "Mozilla",
811 "version": "22.0a1",
812 "xpcomabi": "x86_64-gcc3"
813 },
815 org.mozilla.appInfo.update
816 --------------------------
818 This measurement contains information about the application update mechanism
819 in the application.
821 Version 1
822 ^^^^^^^^^
824 The following daily values are reported:
826 enabled
827 Whether automatic application update checking is enabled. 1 for yes,
828 0 for no.
829 autoDownload
830 Whether automatic download of available updates is enabled.
832 Notes
833 ^^^^^
835 This measurement was merged to mozilla-central for JS FHR on 2013-07-15.
837 Example
838 ^^^^^^^
840 ::
842 "2013-07-15": {
843 "org.mozilla.appInfo.update": {
844 "_v": 1,
845 "enabled": 1,
846 "autoDownload": 1,
847 }
848 }
850 org.mozilla.appInfo.versions
851 ----------------------------
853 This measurement contains a history of application version numbers.
855 Version 2
856 ^^^^^^^^^
858 Version 2 reports more fields than version 1 and is not backwards compatible.
859 The following fields are present in version 2:
861 appVersion
862 An array of application version strings.
863 appBuildID
864 An array of application build ID strings.
865 platformVersion
866 An array of platform version strings.
867 platformBuildID
868 An array of platform build ID strings.
870 When the application is upgraded, the new version and/or build IDs are
871 appended to their appropriate fields.
873 Version 1
874 ^^^^^^^^^
876 When the application version (*version* from *org.mozilla.appinfo.appinfo*)
877 changes, we record the new version on the day the change was seen. The new
878 versions for a day are recorded in an array under the *version* property.
880 Notes
881 ^^^^^
883 If the application isn't upgraded, this measurement will not be present.
884 This means this measurement will not be present for most days if a user is
885 on the release channel (since updates are typically released every 6 weeks).
886 However, users on the Nightly and Aurora channels will likely have a lot
887 of these entries since those builds are updated every day.
889 Values for this measurement are collected when performing the daily
890 collection (typically occurs at upload time). As a result, it's possible
891 the actual upgrade day may not be attributed to the proper day - the
892 reported day may lag behind.
894 The app and platform versions and build IDs should be identical for most
895 clients. If they are different, we are possibly looking at a *Frankenfox*.
897 Example
898 ^^^^^^^
900 ::
902 "2013-03-27": {
903 "org.mozilla.appInfo.versions": {
904 "_v": 2,
905 "appVersion": [
906 "22.0.0"
907 ],
908 "appBuildID": [
909 "20130325031100"
910 ],
911 "platformVersion": [
912 "22.0.0"
913 ],
914 "platformBuildID": [
915 "20130325031100"
916 ]
917 }
918 }
920 org.mozilla.appSessions.current
921 -------------------------------
923 This measurement contains information about the currently running XUL
924 application's session.
926 Version 3
927 ^^^^^^^^^
929 This measurement has the following properties:
931 startDay
932 Integer days since UNIX epoch when this session began.
933 activeTicks
934 Integer count of *ticks* the session was active for. Gecko periodically
935 sends out a signal when the session is active. Session activity
936 involves keyboard or mouse interaction with the application. Each tick
937 represents a window of 5 seconds where there was interaction.
938 totalTime
939 Integer seconds the session has been alive.
940 main
941 Integer milliseconds it took for the Gecko process to start up.
942 firstPaint
943 Integer milliseconds from process start to first paint.
944 sessionRestored
945 Integer milliseconds from process start to session restore.
947 Example
948 ^^^^^^^
950 ::
952 "org.mozilla.appSessions.current": {
953 "_v": 3,
954 "startDay": 15775,
955 "activeTicks": 4282,
956 "totalTime": 249422,
957 "main": 851,
958 "firstPaint": 3271,
959 "sessionRestored": 5998
960 }
962 org.mozilla.appSessions.previous
963 --------------------------------
965 This measurement contains information about previous XUL application sessions.
967 Version 3
968 ^^^^^^^^^
970 This measurement contains per-day lists of all the sessions started on that
971 day. The following properties may be present:
973 cleanActiveTicks
974 Active ticks of sessions that were properly shut down.
975 cleanTotalTime
976 Total number of seconds for sessions that were properly shut down.
977 abortedActiveTicks
978 Active ticks of sessions that were not properly shut down.
979 abortedTotalTime
980 Total number of seconds for sessions that were not properly shut down.
981 main
982 Time in milliseconds from process start to main process initialization.
983 firstPaint
984 Time in milliseconds from process start to first paint.
985 sessionRestored
986 Time in milliseconds from process start to session restore.
988 Notes
989 ^^^^^
991 Sessions are recorded on the date on which they began.
993 If a session was aborted/crashed, the total time may be less than the actual
994 total time. This is because we don't always update total time during periods
995 of inactivity and the abort/crash could occur after a long period of idle,
996 before we've updated the total time.
998 The lengths of the arrays for {cleanActiveTicks, cleanTotalTime},
999 {abortedActiveTicks, abortedTotalTime}, and {main, firstPaint, sessionRestored}
1000 should all be identical.
1002 The length of the clean sessions plus the length of the aborted sessions should
1003 be equal to the length of the {main, firstPaint, sessionRestored} properties.
1005 It is not possible to distinguish the main, firstPaint, and sessionRestored
1006 values from a clean vs aborted session: they are all lumped together.
1008 For sessions spanning multiple UTC days, it's not possible to know which
1009 days the session was active for. It's possible a week long session only
1010 had activity for 2 days and there's no way for us to tell which days.
1012 Example
1013 ^^^^^^^
1015 ::
1017 "org.mozilla.appSessions.previous": {
1018 "_v": 3,
1019 "cleanActiveTicks": [
1020 78,
1021 1785
1022 ],
1023 "cleanTotalTime": [
1024 4472,
1025 88908
1026 ],
1027 "main": [
1028 32,
1029 952
1030 ],
1031 "firstPaint": [
1032 2755,
1033 3497
1034 ],
1035 "sessionRestored": [
1036 5149,
1037 5520
1038 ]
1039 }
1041 org.mozilla.crashes.crashes
1042 ---------------------------
1044 This measurement contains a historical record of application crashes.
1046 Version 2
1047 ^^^^^^^^^
1049 The switch to version 2 coincides with the introduction of the
1050 :ref:`crashes_crashmanager`, which provides a more robust source of
1051 crash data.
1053 This measurement will be reported on each day there was a crash. The
1054 following fields may be present in each record:
1056 mainCrash
1057 The number of main process crashes that occurred on the given day.
1059 Yes, version 2 does not track submissions like version 1. It is very
1060 likely submissions will be re-added later.
1062 Also absent from version 2 are plugin crashes and hangs. These will be
1063 re-added, likely in version 3.
1065 Version 1
1066 ^^^^^^^^^
1068 This measurement will be reported on each day there was a crash. The
1069 following properties are reported:
1071 pending
1072 The number of crash reports that haven't been submitted.
1073 submitted
1074 The number of crash reports that were submitted.
1076 Notes
1077 ^^^^^
1079 Main process crashes are typically submitted immediately after they
1080 occur (by checking a box in the crash reporter, which should appear
1081 automatically after a crash). If the crash reporter submits the crash
1082 successfully, we get a submitted crash. Else, we leave it as pending.
1084 A pending crash does not mean it will eventually be submitted.
1086 Pending crash reports can be submitted post-crash by going to
1087 about:crashes.
1089 If a pending crash is submitted via about:crashes, the submitted count
1090 increments but the pending count does not decrement. This is because FHR
1091 does not know which pending crash was just submitted and therefore it does
1092 not know which day's pending crash to decrement.
1094 Example
1095 ^^^^^^^
1097 ::
1099 "org.mozilla.crashes.crashes": {
1100 "_v": 1,
1101 "pending": 1,
1102 "submitted": 2
1103 },
1104 "org.mozilla.crashes.crashes": {
1105 "_v": 2,
1106 "mainCrash": 2
1107 }
1109 org.mozilla.healthreport.submissions
1110 ------------------------------------
1112 This measurement contains a history of FHR's own data submission activity.
1113 It was added in Firefox 23 in early May 2013.
1115 Version 2
1116 ^^^^^^^^^
1118 This is the same as version 1 except an additional field has been added.
1120 uploadAlreadyInProgress
1121 A request for upload was initiated while another upload was in progress.
1122 This should not occur in well-behaving clients. It (along with a lock
1123 preventing simultaneous upload) was added to ensure this never occurs.
1125 Version 1
1126 ^^^^^^^^^
1128 Daily counts of upload events are recorded.
1130 firstDocumentUploadAttempt
1131 An attempt was made to upload the client's first document to the server.
1132 These are uploads where the client is not aware of a previous document ID
1133 on the server. Unless the client had disabled upload, there should be at
1134 most one of these in the history of the client.
1136 continuationUploadAttempt
1137 An attempt was made to upload a document that replaces an existing document
1138 on the server. Most upload attempts should be attributed to this as opposed
1139 to *firstDocumentUploadAttempt*.
1141 uploadSuccess
1142 The upload attempt recorded by *firstDocumentUploadAttempt* or
1143 *continuationUploadAttempt* was successful.
1145 uploadTransportFailure
1146 An upload attempt failed due to transport failure (network unavailable,
1147 etc).
1149 uploadServerFailure
1150 An upload attempt failed due to a server-reported failure. Ideally these
1151 are failures reported by the FHR server itself. However, intermediate
1152 proxies, firewalls, etc may trigger this depending on how things are
1153 configured.
1155 uploadClientFailure
1156 An upload attempt failued due to an error/exception in the client.
1157 This almost certainly points to a bug in the client.
1159 The result for an upload attempt is always attributed to the same day as
1160 the attempt, even if the result occurred on a different day from the attempt.
1161 Therefore, the sum of the result counts should equal the result of the attempt
1162 counts.
1164 org.mozilla.places.places
1165 -------------------------
1167 This measurement contains information about the Places database (where Firefox
1168 stores its history and bookmarks).
1170 Version 1
1171 ^^^^^^^^^
1173 Daily counts of items in the database are reported in the following properties:
1175 bookmarks
1176 Integer count of bookmarks present.
1177 pages
1178 Integer count of pages in the history database.
1180 Example
1181 ^^^^^^^
1183 ::
1185 "org.mozilla.places.places": {
1186 "_v": 1,
1187 "bookmarks": 388,
1188 "pages": 94870
1189 }
1191 org.mozilla.profile.age
1192 -----------------------
1194 This measurement contains information about the current profile's age.
1196 Version 1
1197 ^^^^^^^^^
1199 A single *profileCreation* property is present. It defines the integer
1200 days since UNIX epoch that the current profile was created.
1202 Notes
1203 ^^^^^
1205 It is somewhat difficult to obtain a reliable *profile born date* due to a
1206 number of factors.
1208 Example
1209 ^^^^^^^
1211 ::
1213 "org.mozilla.profile.age": {
1214 "_v": 1,
1215 "profileCreation": 15176
1216 }
1218 org.mozilla.searches.counts
1219 ---------------------------
1221 This measurement contains information about searches performed in the
1222 application.
1224 Version 2
1225 ^^^^^^^^^
1227 This behaves like version 1 except we added all search engines that
1228 Mozilla has a partner agreement with. Like version 1, we concatenate
1229 a search engine ID with a search origin.
1231 Another difference with version 2 is we should no longer misattribute
1232 a search to the *other* bucket if the search engine name is localized.
1234 The set of search engine providers is:
1236 * amazon-co-uk
1237 * amazon-de
1238 * amazon-en-GB
1239 * amazon-france
1240 * amazon-it
1241 * amazon-jp
1242 * amazondotcn
1243 * amazondotcom
1244 * amazondotcom-de
1245 * aol-en-GB
1246 * aol-web-search
1247 * bing
1248 * eBay
1249 * eBay-de
1250 * eBay-en-GB
1251 * eBay-es
1252 * eBay-fi
1253 * eBay-france
1254 * eBay-hu
1255 * eBay-in
1256 * eBay-it
1257 * google
1258 * google-jp
1259 * google-ku
1260 * google-maps-zh-TW
1261 * mailru
1262 * mercadolibre-ar
1263 * mercadolibre-cl
1264 * mercadolibre-mx
1265 * seznam-cz
1266 * twitter
1267 * twitter-de
1268 * twitter-ja
1269 * yahoo
1270 * yahoo-NO
1271 * yahoo-answer-zh-TW
1272 * yahoo-ar
1273 * yahoo-bid-zh-TW
1274 * yahoo-br
1275 * yahoo-ch
1276 * yahoo-cl
1277 * yahoo-de
1278 * yahoo-en-GB
1279 * yahoo-es
1280 * yahoo-fi
1281 * yahoo-france
1282 * yahoo-fy-NL
1283 * yahoo-id
1284 * yahoo-in
1285 * yahoo-it
1286 * yahoo-jp
1287 * yahoo-jp-auctions
1288 * yahoo-mx
1289 * yahoo-sv-SE
1290 * yahoo-zh-TW
1291 * yandex
1292 * yandex-ru
1293 * yandex-slovari
1294 * yandex-tr
1295 * yandex.by
1296 * yandex.ru-be
1298 And of course, *other*.
1300 The sources for searches remain:
1302 * abouthome
1303 * contextmenu
1304 * searchbar
1305 * urlbar
1307 The measurement will only be populated with providers and sources that
1308 occurred that day.
1310 If a user switches locales, searches from default providers on the older
1311 locale will still be supported. However, if that same search engine is
1312 added by the user to the new build and is *not* a default search engine
1313 provider, its searches will be attributed to the *other* bucket.
1315 Version 1
1316 ^^^^^^^^^
1318 We record counts of performed searches grouped by search engine and search
1319 origin. Only search engines with which Mozilla has a business relationship
1320 are explicitly counted. All other search engines are grouped into an
1321 *other* bucket.
1323 The following search engines are explicitly counted:
1325 * Amazon.com
1326 * Bing
1327 * Google
1328 * Yahoo
1329 * Other
1331 The following search origins are distinguished:
1333 about:home
1334 Searches initiated from the search text box on about:home.
1335 context menu
1336 Searches initiated from the context menu (highlight text, right click,
1337 and select "search for...")
1338 search bar
1339 Searches initiated from the search bar (the text field next to the
1340 Awesomebar)
1341 url bar
1342 Searches initiated from the awesomebar/url bar.
1344 Due to the localization of search engine names, non en-US locales may wrongly
1345 attribute searches to the *other* bucket. This is fixed in version 2.
1347 Example
1348 ^^^^^^^
1350 ::
1352 "org.mozilla.searches.counts": {
1353 "_v": 1,
1354 "google.searchbar": 3,
1355 "google.urlbar": 7
1356 },
1358 org.mozilla.searches.engines
1359 ----------------------------
1361 This measurement contains information about search engines.
1363 Version 1
1364 ^^^^^^^^^
1366 This version debuted with Firefox 31 on desktop. It contains the
1367 following properties:
1369 default
1370 Daily string identifier or name of the default search engine provider.
1372 This field will only be collected if Telemetry is enabled. If
1373 Telemetry is enabled and then later disabled, this field may
1374 disappear from future days in the payload.
1376 The special value ``NONE`` could occur if there is no default search
1377 engine.
1379 The special value ``UNDEFINED`` could occur if a default search
1380 engine exists but its identifier could not be determined.
1382 This field's contents are
1383 ``Services.search.defaultEngine.identifier`` (if defined) or
1384 ``"other-"`` + ``Services.search.defaultEngine.name`` if not.
1385 In other words, search engines without an ``.identifier``
1386 are prefixed with ``other-``.
1388 org.mozilla.sync.sync
1389 ---------------------
1391 This daily measurement contains information about the Sync service.
1393 Values should be recorded for every day FHR measurements occurred.
1395 Version 1
1396 ^^^^^^^^^
1398 This version debuted with Firefox 30 on desktop. It contains the following
1399 properties:
1401 enabled
1402 Daily numeric indicating whether Sync is configured and enabled. 1 if so,
1403 0 otherwise.
1405 preferredProtocol
1406 String version of the maximum Sync protocol version the client supports.
1407 This will be ``1.1`` for for legacy Sync and ``1.5`` for clients that
1408 speak the Firefox Accounts protocol.
1410 actualProtocol
1411 The actual Sync protocol version the client is configured to use.
1413 This will be ``1.1`` if the client is configured with the legacy Sync
1414 service or if the client only supports ``1.1``.
1416 It will be ``1.5`` if the client supports ``1.5`` and either a) the
1417 client is not configured b) the client is using Firefox Accounts Sync.
1419 syncStart
1420 Count of sync operations performed.
1422 syncSuccess
1423 Count of sync operations that completed successfully.
1425 syncError
1426 Count of sync operations that did not complete successfully.
1428 This is a measure of overall sync success. This does *not* reflect
1429 recoverable errors (such as record conflict) that can occur during
1430 sync. This is thus a rough proxy of whether the sync service is
1431 operating without error.
1433 org.mozilla.sync.devices
1434 ------------------------
1436 This daily measurement contains information about the device type composition
1437 for the configured Sync account.
1439 Version 1
1440 ^^^^^^^^^
1442 Version 1 was introduced with Firefox 30.
1444 Field names are dynamic according to the client-reported device types from
1445 Sync records. All fields are daily last seen integer values corresponding to
1446 the number of devices of that type.
1448 Common values include:
1450 desktop
1451 Corresponds to a Firefox desktop client.
1453 mobile
1454 Corresponds to a Fennec client.
1456 org.mozilla.sysinfo.sysinfo
1457 ---------------------------
1459 This measurement contains basic information about the system the application
1460 is running on.
1462 Version 2
1463 ^^^^^^^^^
1465 This version debuted with Firefox 29 on desktop.
1467 A single property was introduced.
1469 isWow64
1470 If present, this property indicates whether the machine supports WoW64.
1471 This property can be used to identify whether the host machine is 64-bit.
1473 This property is only present on Windows machines. It is the preferred way
1474 to identify 32- vs 64-bit support in that environment.
1476 Version 1
1477 ^^^^^^^^^
1479 The following properties may be available:
1481 cpuCount
1482 Integer number of CPUs/cores in the machine.
1483 memoryMB
1484 Integer megabytes of memory in the machine.
1485 manufacturer
1486 The manufacturer of the device.
1487 device
1488 The name of the device (like model number).
1489 hardware
1490 Unknown.
1491 name
1492 OS name.
1493 version
1494 OS version.
1495 architecture
1496 OS architecture that the application is built for. This is not the
1497 actual system architecture.
1499 Example
1500 ^^^^^^^
1502 ::
1504 "org.mozilla.sysinfo.sysinfo": {
1505 "_v": 1,
1506 "cpuCount": 8,
1507 "memoryMB": 8192,
1508 "architecture": "x86-64",
1509 "name": "Darwin",
1510 "version": "12.2.0"
1511 }
1515 org.mozilla.experiments.info
1516 ----------------------------------
1518 Daily measurement reporting information about the Telemetry Experiments service.
1520 Version 1
1521 ^^^^^^^^^
1523 Property:
1525 lastActive
1526 ID of the final Telemetry Experiment that is active on a given day, if any.
1529 Version 2
1530 ^^^^^^^^^
1532 Adds an additional optional property:
1534 lastActiveBranch
1535 If the experiment uses branches, the branch identifier string.
1537 Example
1538 ^^^^^^^
1540 ::
1542 "org.mozilla.experiments.info": {
1543 "_v": 2,
1544 "lastActive": "some.experiment.id",
1545 "lastActiveBranch": "control"
1546 }
