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