1 files changed, 175 insertions, 0 deletions
diff --git a/comm/mail/components/telemetry/README.md b/comm/mail/components/telemetry/README.md
new file mode 100644
index 0000000000..45b7dda9fe
--- /dev/null
+++ b/comm/mail/components/telemetry/README.md
@@ -0,0 +1,175 @@
+# Notes on telemetry in Thunderbird
+
+## Hooking into the build process
+
+The comm-central probe definitions in this directory (`Events.yaml`,
+`Scalars.yaml` and `Histograms.json`) are used _in addition_ to
+their mozilla-central counterparts (in `toolkit/components/telemetry/`).
+
+As part of the mozilla-central telemetry build process, scripts are used to
+generate the C++ files which define the probe registry (enums, string tables
+etc).
+
+Because of this code generation, the extra comm-central probe definitions
+need to be included when the mozilla-central telemetry is built.
+
+This is done by setting `MOZ_TELEMETRY_EXTRA_*` config values. You can
+see these in `comm/mail/moz.configure`.
+These config values are used by `toolkit/components/telemetry/moz.build`
+(mozilla-central) to pass the extra probe definitions to the code
+generation scripts.
+
+The build scripts can be found under `toolkit/components/telemetry/build_scripts`.
+They are written in Python.
+
+## Naming probes
+
+To avoid clashing with the mozilla-central probes, we'll be pretty liberal
+about slapping on prefixes to our definitions.
+
+For Events and Scalars, we keep everything under `tb.`.
+
+For Histograms, we use a `TB_` or `TELEMETRY_TEST_TB_` prefix.
+
+(Why not just `TB_`? Because the telemetry test helper functions
+`getSnapshotForHistograms()`/`getSnapshotForKeyedHistograms()` have an option
+to filter out histograms with a `TELEMETRY_TEST_` prefix).
+
+## Compile-time switches
+
+Telemetry is not compiled in by default. You need to add the following line
+to your mozconfig:
+
+    export MOZ_TELEMETRY_REPORTING=1
+
+The nightly and release configs have this setting already (`$ grep -r MOZ_TELEMETRY_ mail/config/mozconfigs`).
+
+## Runtime prefs for testing
+
+There are a few `user.js` settings you'll want to set up for enabling telemetry local builds:
+
+### Send telemetry to a local server
+
+You'll want to set the telemetry end point to a locally-running http server, eg:
+```
+user_pref("toolkit.telemetry.server", "http://localhost:12345");
+user_pref("toolkit.telemetry.server_owner", "TimmyTestfish");
+user_pref("datareporting.healthreport.uploadEnabled",true);
+```
+
+For a simple test server, try https://github.com/mozilla/gzipServer
+(or alternatively https://github.com/bcampbell/webhole).
+
+### Override the official-build-only check
+
+```
+user_pref("toolkit.telemetry.send.overrideOfficialCheck", true);
+```
+
+Without toolkit.telemetry.send.overrideOfficialCheck set, telemetry is only sent for official builds.
+
+### Bypass data policy checks
+
+The data policy checks make sure the user has been shown and
+has accepted the data policy. Bypass them with:
+
+```
+user_pref("datareporting.policy.dataSubmissionPolicyBypassNotification",true);
+user_pref("datareporting.policy.dataSubmissionEnabled", true);
+```
+
+### Enable telemetry tracing
+
+```
+user_pref("toolkit.telemetry.log.level", "Trace");
+```
+
+The output will show up on the DevTools console:
+
+    Menu => "Tools" => "Developer Tools" => "Error Console"  (CTRL+SHIFT+J)
+
+If pings aren't showing up, look there for clues.
+
+To log to stdout as well as the console:
+```
+user_pref("toolkit.telemetry.log.dump", true);
+```
+
+### Reduce submission interval
+
+For testing it can be handy to reduce down the submission interval (it's
+usually on the order of hours), eg:
+```
+user_pref("services.sync.telemetry.submissionInterval", 20); // in seconds
+```
+
+### Example user.js file
+
+All the above suggestions in one go, for `$PROFILE/user.js`:
+
+```
+user_pref("toolkit.telemetry.server", "http://localhost:12345");
+user_pref("toolkit.telemetry.server_owner", "TimmyTestfish");
+user_pref("toolkit.telemetry.log.level", "Trace");
+user_pref("toolkit.telemetry.log.dump", true);
+user_pref("toolkit.telemetry.send.overrideOfficialCheck", true);
+user_pref("datareporting.policy.dataSubmissionPolicyBypassNotification",true);
+user_pref("services.sync.telemetry.submissionInterval", 20);
+user_pref("datareporting.policy.dataSubmissionEnabled", true);
+user_pref("datareporting.healthreport.uploadEnabled",true);
+```
+
+## Troubleshooting
+
+### Sending test pings
+
+From the DevTools console, you can send an immediate test ping:
+
+```
+const { TelemetrySession } = ChromeUtils.import(
+  "resource://gre/modules/TelemetrySession.jsm"
+);
+TelemetrySession.testPing();
+```
+
+### Trace message: "Telemetry is not allowed to send pings"
+
+This indicates `TelemetrySend.sendingEnabled()` is returning false;
+
+Fails if not an official build (override using `toolkit.telemetry.send.overrideOfficialCheck`).
+
+If `toolkit.telemetry.unified` and `datareporting.healthreport.uploadEnabled` are true, then
+`sendingEnabled()` returns true;
+
+If `toolkit.telemetry.unified` is false, then the intended-to-be-deprecated `toolkit.telemetry.enabled` controls the result.
+We're using unified telemetry, so this shouldn't be an issue.
+
+### Trace message: "can't send ping now, persisting to disk"
+
+Trace shows:
+```
+TelemetrySend::submitPing - can't send ping now, persisting to disk - canSendNow: false
+```
+
+This means `TelemetryReportingPolicy.canUpload()` is returning false.
+
+Requirements for `canUpload()`:
+
+`datareporting.policy.dataSubmissionEnabled` must be true.
+AND
+`datareporting.policy.dataSubmissionPolicyNotifiedTime` has a sane timestamp (and is > `OLDEST_ALLOWED_ACCEPTANCE_YEAR`).
+AND
+`datareporting.policy.dataSubmissionPolicyAcceptedVersion` >= `datareporting.policy.minimumPolicyVersion`
+
+Or the notification policy can be bypassed by setting:
+`datareporting.policy.dataSubmissionPolicyBypassNotification` to true.
+
+## Further documentation
+
+The Telemetry documentation index is at:
+
+https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/index.html
+
+There's a good summary of settings (both compile-time and run-time prefs):
+
+https://firefox-source-docs.mozilla.org/toolkit/components/telemetry/telemetry/internals/preferences.html