diff options
Diffstat (limited to '')
-rw-r--r-- | comm/mail/components/telemetry/Events.yaml | 25 | ||||
-rw-r--r-- | comm/mail/components/telemetry/Histograms.json | 40 | ||||
-rw-r--r-- | comm/mail/components/telemetry/README.md | 175 | ||||
-rw-r--r-- | comm/mail/components/telemetry/Scalars.yaml | 591 |
4 files changed, 831 insertions, 0 deletions
diff --git a/comm/mail/components/telemetry/Events.yaml b/comm/mail/components/telemetry/Events.yaml new file mode 100644 index 0000000000..bc3772ee46 --- /dev/null +++ b/comm/mail/components/telemetry/Events.yaml @@ -0,0 +1,25 @@ +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, you can obtain one at http://mozilla.org/MPL/2.0/. + +# This file contains Thunderbird-specific telemetry Event definitions, which +# are added on top of the Firefox ones (in /toolkit/components/telemetry). +# To avoid name clashes, all the Thunderbird events will be under a "tb" +# category. + +# A category used for unit tests. +# Under normal operation, these won't be invoked. +tb.test: + test: + objects: ["object1", "object2", "object3"] + bug_numbers: [1427877] + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: ["main"] + description: This is a test entry for Telemetry. + expiry_version: never + extra_keys: + key1: This is just a test description. + products: + - thunderbird + diff --git a/comm/mail/components/telemetry/Histograms.json b/comm/mail/components/telemetry/Histograms.json new file mode 100644 index 0000000000..568887be1b --- /dev/null +++ b/comm/mail/components/telemetry/Histograms.json @@ -0,0 +1,40 @@ +{ + "TELEMETRY_TEST_TB_CATEGORICAL": { + "record_in_processes": ["main", "content"], + "products": ["thunderbird"], + "alert_emails": ["telemetry-client-dev@thunderbird.net"], + "bug_numbers": [1427877], + "expires_in_version": "never", + "kind": "categorical", + "labels": ["CommonLabel", "Label2", "Label3"], + "description": "A testing histogram; not meant to be touched" + }, + "TB_COMPOSE_TYPE": { + "record_in_processes": ["main"], + "products": ["thunderbird"], + "alert_emails": ["telemetry-client-dev@thunderbird.net"], + "bug_numbers": [1615996], + "expires_in_version": "never", + "kind": "categorical", + "labels": [ + "New", + "Reply", + "ReplyAll", + "ForwardAsAttachment", + "ForwardInline", + "NewsPost", + "ReplyToSender", + "ReplyToGroup", + "ReplyToSenderGroup", + "Draft", + "Template", + "MailToUrl", + "ReplyWithTemplate", + "ReplyToList", + "Redirect", + "EditAsNew", + "EditTemplate" + ], + "description": "Histogram of different message compose types used" + } +} 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 diff --git a/comm/mail/components/telemetry/Scalars.yaml b/comm/mail/components/telemetry/Scalars.yaml new file mode 100644 index 0000000000..13ac19fcdd --- /dev/null +++ b/comm/mail/components/telemetry/Scalars.yaml @@ -0,0 +1,591 @@ +# This Source Code Form is subject to the terms of the Mozilla Public +# License, v. 2.0. If a copy of the MPL was not distributed with this +# file, you can obtain one at http://mozilla.org/MPL/2.0/. + +# This file contains Thunderbird-specific telemetry Scalar definitions, which +# are added on top of the Firefox ones (in /toolkit/components/telemetry). +# To avoid name clashes, all the TB scalars will be under a "tb" section. +# They are submitted with the "main" pings and can be inspected in about:telemetry. + +# The following section is for probes testing the Telemetry system. +# Under normal operation, these won't be invoked. +tb.test: + unsigned_int_kind: + bug_numbers: + - 1427877 + description: > + This is a test uint type with a really long description, maybe spanning even multiple + lines, to just prove a point: everything works just fine. + expires: never + products: + - 'thunderbird' + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + string_kind: + bug_numbers: + - 1427877 + description: A string test type with a one line comment that works just fine! + expires: never + products: + - 'thunderbird' + kind: string + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + boolean_kind: + bug_numbers: + - 1427877 + description: A boolean test type with a one line comment that works just fine! + expires: never + products: + - 'thunderbird' + kind: boolean + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + +tb.account: + count: + bug_numbers: + - 1615981 + description: Count of how many accounts were set up, keyed by account type. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + successful_email_account_setup: + bug_numbers: + - 1615987 + - 1644311 + description: How many times email accounts setup succeeded, keyed by account config source. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + failed_email_account_setup: + bug_numbers: + - 1615987 + - 1644311 + description: How many times email accounts setup failed, keyed by account config source. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + size_on_disk: + bug_numbers: + - 1615983 + description: How many bytes does each type of folder take on disk. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + total_messages: + bug_numbers: + - 1615983 + description: How many messages does each type of folder have. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + opened_account_provisioner: + bug_numbers: + - 1734484 + description: How many times the user access the account provisioner tab. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + selected_account_from_provisioner: + bug_numbers: + - 1734484 + description: + How many times the user clicks on a suggested email address from the + account provisioner tab, keyed by the provider hostname. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + new_account_from_provisioner: + bug_numbers: + - 1734484 + description: + How many times a new email address was successfully created from the + account provisioner tab, keyed by the provider hostname. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + oauth2_provider_count: + bug_numbers: + - 1799726 + description: + A count of incoming mail accounts using OAuth2 for authentication, keyed + broadly by account provider. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + +tb.compose: + format_html: + bug_numbers: + - 1584889 + description: How many times messages were written in HTML composition mode. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + format_plain_text: + bug_numbers: + - 1584889 + description: How many times messages were written in plain text composition mode. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + +tb.filelink: + uploaded_size: + bug_numbers: + - 1615984 + description: Accumulated file size (bytes) uploaded to filelink services, keyed by filelink provider type. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + ignored: + bug_numbers: + - 1615984 + description: How many times filelink suggestion are ignored. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + +tb.mails: + sent: + bug_numbers: + - 1615989 + description: How many emails are sent. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + read: + bug_numbers: + - 1615990 + description: How many emails are read. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + read_secure: + bug_numbers: + - 1615994 + description: How many times different kinds of secure emails are read (for the first time). + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + keys: + - 'signed-smime' + - 'signed-openpgp' + - 'encrypted-smime' + - 'encrypted-openpgp' + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + folder_opened: + bug_numbers: + - 1800775 + description: How many times folders of each type are opened. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + kind: uint + keyed: true + keys: + - Inbox + - Drafts + - Trash + - SentMail + - Templates + - Junk + - Archive + - Queue + - Virtual + - Other + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + +tb.preferences: + boolean: + bug_numbers: + - 1757993 + description: Values of boolean preferences. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: boolean + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + integer: + bug_numbers: + - 1800775 + description: Values of integer preferences. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + +tb.websearch: + usage: + bug_numbers: + - 1641773 + description: How many times search the web was used, keyed by search engine name. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + +tb.addressbook: + addressbook_count: + bug_numbers: + - 1615986 + description: How many addressbooks were set up, keyed by addressbook directory URI scheme. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + contact_count: + bug_numbers: + - 1615986 + description: Count of contacts in all addressbooks, keyed by addressbook directory URI scheme. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + +tb.calendar: + calendar_count: + bug_numbers: + - 1615985 + description: How many calendars were set up, keyed by calendar type. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + read_only_calendar_count: + bug_numbers: + - 1615985 + description: How many read only calendars were set up, keyed by calendar type. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + keyed: true + kind: uint + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + +tb.ui.configuration: + folder_tree_modes: + bug_numbers: + - 1800775 + description: Configuration of the folder tree. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + kind: string + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + pane_visibility: + bug_numbers: + - 1800775 + description: Configuration of the folder and message panes. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + kind: boolean + keyed: true + keys: + - folderPane + - messagePane + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + + message_header: + bug_numbers: + - 1800775 + description: Configuration of the message header display. + release_channel_collection: opt-out + expires: never + products: + - 'thunderbird' + kind: uint + keyed: true + keys: + - showAvatar + - showBigAvatar + - showFullAddress + - hideLabels + - subjectLarge + - buttonStyle + notification_emails: + - "telemetry-client-dev@thunderbird.net" + record_in_processes: + - 'main' + +tb.ui.interaction: + calendar: + bug_numbers: + - 1736739 + description: > + Records a count of interactions with items in the calendar. + expires: never + kind: uint + keyed: true + notification_emails: + - "telemetry-client-dev@thunderbird.net" + products: + - "thunderbird" + release_channel_collection: opt-out + record_in_processes: + - "main" + + chat: + bug_numbers: + - 1736739 + description: > + Records a count of interactions with items in chat. + expires: never + kind: uint + keyed: true + notification_emails: + - "telemetry-client-dev@thunderbird.net" + products: + - "thunderbird" + release_channel_collection: opt-out + record_in_processes: + - "main" + + keyboard: + bug_numbers: + - 1736739 + description: > + Records a count of interactions with keyboard shortcuts. + expires: never + kind: uint + keyed: true + notification_emails: + - "telemetry-client-dev@thunderbird.net" + products: + - "thunderbird" + release_channel_collection: opt-out + record_in_processes: + - "main" + + message_display: + bug_numbers: + - 1736739 + description: > + Records a count of interactions with items in the message display. + expires: never + kind: uint + keyed: true + notification_emails: + - "telemetry-client-dev@thunderbird.net" + products: + - "thunderbird" + release_channel_collection: opt-out + record_in_processes: + - "main" + + toolbox: + bug_numbers: + - 1736739 + description: > + Records a count of interactions with items in the main window toolbox. + expires: never + kind: uint + keyed: true + notification_emails: + - "telemetry-client-dev@thunderbird.net" + products: + - "thunderbird" + release_channel_collection: opt-out + record_in_processes: + - "main" + +tb.chat: + active_message_theme: + bug_numbers: + - 1767004 + description: > + Records the currently active chat message theme and variant. + expires: "117" + kind: string + keyed: false + notification_emails: + - "telemetry-client-dev@thunderbird.net" + products: + - "thunderbird" + release_channel_collection: opt-out + record_in_processes: + - "main" |