1Ecosystem Telemetry
2===================
3
4This module transmits Ecosystem Telemetry from Firefox Desktop.
5It is only sent for Firefox Account users, using a single ping type
6"account-ecosystem"
7
8.. note::
9
10  You might like to read the `background information on Ecosystem
11  Telemetry <https://mozilla.github.io/ecosystem-platform/docs/features/firefox-accounts/ecosystem-telemetry/>`_
12
13The existing telemetry client id is **not** submitted with the ping, but an
14"ecosystem client id" is - this has the same semantics as the existing
15client id, although is a different value, and is not sent in any other ping.
16
17An anonymized user ID is submitted with each ping - `read more about these
18IDs and how they're designed to safeguard user privacy <https://mozilla.github.io/ecosystem-platform/docs/features/firefox-accounts/ecosystem-telemetry/>`_
19
20A reduced Telemetry environment is submitted in the ping, as described below.
21
22Environment
23-----------
24
25In an effort to reduce the possibility of fingerprinting, we only provide the
26following environment subset:
27
28.. code-block:: js
29
30    {
31      settings: {
32        locale: <string>, // e.g. "it", null on failure
33      },
34      system: {
35        memoryMB: <number>,
36        os: {
37            name: <string>, // e.g. "Windows_NT", null on failure
38            version: <string>, // e.g. "6.1", null on failure
39            locale: <string>, // "en" or null on failure
40        },
41        cpu: {
42          speedMHz: <number>, // cpu clock speed in MHz
43        }
44      },
45      profile: {
46        creationDate: <integer>, // integer days since UNIX epoch, e.g. 16446
47        firstUseDate: <integer>, // integer days since UNIX epoch, e.g. 16446 - optional
48      }
49    }
50
51account-ecosystem ping
52----------------------
53
54.. code-block:: js
55
56    {
57      "type": "account-ecosystem",
58      ... common ping data
59      "environment": { ... }, // as above
60      "payload": {
61        "reason": <string>, // Why the ping was submitted
62        "ecosystemAnonId": <string>, // The anonymized ID, as described above.
63        "ecosystemClientId": <guid>, // The ecosystem client ID as described above.
64        "duration": <number>, // duration since ping was last sent or since the beginning of the Firefox session in seconds
65        "histograms": {...},
66        "keyedHistograms": {...},
67        "scalars": {...},
68        "keyedScalars": {...},
69      }
70    }
71
72reason
73~~~~~~
74The ``reason`` field contains the information about why the "account-ecosystem" ping was submitted:
75
76* ``periodic`` - Sent roughly every 24 hours
77* ``shutdown`` - Sent on shutdown
78* ``logout`` - Sent when the user logs out
79
80histograms and keyedHistograms
81~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
82This section contains the :doc:`../collection/histograms` that are valid for the account-ecosystem ping, per process.
83The recorded histograms are described in `Histograms.json <https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/Histograms.json>`_, marked with the `account-ecosystem` store.
84
85scalars and keyedScalars
86~~~~~~~~~~~~~~~~~~~~~~~~
87This section contains the :doc:`../collection/scalars` that are valid for the account-ecosystem ping, per process.
88Scalars are only submitted if data was added to them.
89The recorded scalars are described in `Scalars.yaml <https://searchfox.org/mozilla-central/source/toolkit/components/telemetry/Scalars.yaml>`_, marked with the `account-ecosystem` store.
90
91Send behavior
92-------------
93
94Without an account
95~~~~~~~~~~~~~~~~~~
96
97Never.
98
99When a user logs into Firefox Accounts, this ping is submitted as described in
100"With an account" below. No ping is immediately sent.
101
102With an account
103~~~~~~~~~~~~~~~
104
105The ping is submitted; roughly every 24 hours with reason *periodic*. On
106shutdown this ping is submitted with reason *shutdown*.
107
108If the user logs out and disconnects the account, this ping is submitted with
109reason *logout*. While logged out, no pings will be submitted.
110