1# Notes on telemetry in Thunderbird
2
3## Hooking into the build process
4
5The comm-central probe definitions in this directory (`Events.yaml`,
6`Scalars.yaml` and `Histograms.json`) are used _in addition_ to
7their mozilla-central counterparts (in `toolkit/components/telemetry/`).
8
9As part of the mozilla-central telemetry build process, scripts are used to
10generate the C++ files which define the probe registry (enums, string tables
11etc).
12
13Because of this code generation, the extra comm-central probe definitions
14need to be included when the mozilla-central telemetry is built.
15
16This is done by setting `MOZ_TELEMETRY_EXTRA_*` config values. You can
17see these in `comm/mail/moz.configure`.
18These config values are used by `toolkit/components/telemetry/moz.build`
19(mozilla-central) to pass the extra probe definitions to the code
20generation scripts.
21
22The build scripts can be found under `toolkit/components/telemetry/build_scripts`.
23They are written in Python.
24
25## Naming probes
26
27To avoid clashing with the mozilla-central probes, we'll be pretty liberal
28about slapping on prefixes to our definitions.
29
30For Events and Scalars, we keep everything under `tb.`.
31
32For Histograms, we use a `TB_` or `TELEMETRY_TEST_TB_` prefix.
33
34(Why not just `TB_`? Because the telemetry test helper functions
35`getSnapshotForHistograms()`/`getSnapshotForKeyedHistograms()` have an option
36to filter out histograms with a `TELEMETRY_TEST_` prefix).
37
38## Compile-time switches
39
40Telemetry is not compiled in by default. You need to add the following line
41to your mozconfig:
42
43    export MOZ_TELEMETRY_REPORTING=1
44
45The nightly and release configs have this setting already (`$ grep -r MOZ_TELEMETRY_ mail/config/mozconfigs`).
46
47## Runtime prefs for testing
48
49There are a few `user.js` settings you'll want to set up for enabling telemetry local builds:
50
51### Send telemetry to a local server
52
53You'll want to set the telemetry end point to a locally-running http server, eg:
54```
55user_pref("toolkit.telemetry.server", "http://localhost:12345");
56user_pref("toolkit.telemetry.server_owner", "TimmyTestfish");
57user_pref("datareporting.healthreport.uploadEnabled",true);
58```
59
60For a simple test server, try https://github.com/mozilla/gzipServer
61(or alternatively https://github.com/bcampbell/webhole).
62
63### Override the official-build-only check
64
65```
66user_pref("toolkit.telemetry.send.overrideOfficialCheck", true);
67```
68
69Without toolkit.telemetry.send.overrideOfficialCheck set, telemetry is only sent for official builds.
70
71### Bypass data policy checks
72
73The data policy checks make sure the user has been shown and
74has accepted the data policy. Bypass them with:
75
76```
77user_pref("datareporting.policy.dataSubmissionPolicyBypassNotification",true);
78user_pref("datareporting.policy.dataSubmissionEnabled", true);
79```
80
81### Enable telemetry tracing
82
83```
84user_pref("toolkit.telemetry.log.level", "Trace");
85```
86
87The output will show up on the DevTools console:
88
89    Menu => "Tools" => "Developer Tools" => "Error Console"  (CTRL+SHIFT+J)
90
91If pings aren't showing up, look there for clues.
92
93To log to stdout as well as the console:
94```
95user_pref("toolkit.telemetry.log.dump", true);
96```
97
98### Reduce submission interval
99
100For testing it can be handy to reduce down the submission interval (it's
101usually on the order of hours), eg:
102```
103user_pref("services.sync.telemetry.submissionInterval", 20); // in seconds
104```
105
106### Example user.js file
107
108All the above suggestions in one go, for `$PROFILE/user.js`:
109
110```
111user_pref("toolkit.telemetry.server", "http://localhost:12345");
112user_pref("toolkit.telemetry.server_owner", "TimmyTestfish");
113user_pref("toolkit.telemetry.log.level", "Trace");
114user_pref("toolkit.telemetry.log.dump", true);
115user_pref("toolkit.telemetry.send.overrideOfficialCheck", true);
116user_pref("datareporting.policy.dataSubmissionPolicyBypassNotification",true);
117user_pref("services.sync.telemetry.submissionInterval", 20);
118user_pref("datareporting.policy.dataSubmissionEnabled", true);
119user_pref("datareporting.healthreport.uploadEnabled",true);
120```
121
122## Troubleshooting
123
124### Sending test pings
125
126From the DevTools console, you can send an immediate test ping:
127
128```
129Cu.import("resource://gre/modules/TelemetrySession.jsm");
130TelemetrySession.testPing();
131```
132
133### Trace message: "Telemetry is not allowed to send pings"
134
135This indicates `TelemetrySend.sendingEnabled()` is returning false;
136
137Fails if not an official build (override using `toolkit.telemetry.send.overrideOfficialCheck`).
138
139If `toolkit.telemetry.unified` and `datareporting.healthreport.uploadEnabled` are true, then
140`sendingEnabled()` returns true;
141
142If `toolkit.telemetry.unified` is false, then the intended-to-be-deprecated `toolkit.telemetry.enabled` controls the result.
143We're using unified telemetry, so this shouldn't be an issue.
144
145### Trace message: "can't send ping now, persisting to disk"
146
147Trace shows:
148```
149TelemetrySend::submitPing - can't send ping now, persisting to disk - canSendNow: false
150```
151
152This means `TelemetryReportingPolicy.canUpload()` is returning false.
153
154Requirements for `canUpload()`:
155
156`datareporting.policy.dataSubmissionEnabled` must be true.
157AND
158`datareporting.policy.dataSubmissionPolicyNotifiedTime` has a sane timestamp (and is > `OLDEST_ALLOWED_ACCEPTANCE_YEAR`).
159AND
160`datareporting.policy.dataSubmissionPolicyAcceptedVersion` >= `datareporting.policy.minimumPolicyVersion`
161
162Or the notification policy can be bypassed by setting:
163`datareporting.policy.dataSubmissionPolicyBypassNotification` to true.
164
165## Further documentation
166
167The Telemetry documentation index is at:
168
169https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/index.html
170
171There's a good summary of settings (both compile-time and run-time prefs):
172
173https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/internals/preferences.html
174
175