diff --git a/telemetry/README.md b/telemetry/README.md index d6c5662b58..26eb6687a7 100644 --- a/telemetry/README.md +++ b/telemetry/README.md @@ -1,11 +1,9 @@ # Glean Development Guide -*This is a work in progress!* +The [Glean](https://mozilla.github.io/glean/book/index.html) `metrics.yaml` file is the brain - it defines all the metrics we want to track and is used to build the necessary files and functions that we need to send events & corresponding data. I recommend reading through the [Metrics YAML Registry docs](https://mozilla.github.io/glean/book/reference/yaml/metrics.html) to get a good understanding of the different parts of the `metrics.yaml` file and what each piece of info is used for. ## Updating the `metrics.yaml` file -The [Glean](https://mozilla.github.io/glean/book/index.html) `metrics.yaml` file is the brain - it defines all the metrics we want to track and is used to build the necessary files and functions that we need to send events & corresponding data. I recommend reading through the [Metrics YAML Registry docs](https://mozilla.github.io/glean/book/reference/yaml/metrics.html) to get a good understanding of the different parts of the `metrics.yaml` file and what each piece of info is used for. - Currently, in an effort to keep our metrics as consistent as possible across clients, we are referencing a shared [`metrics.yaml`](https://gist.github.com/kirill-demtchouk/41a38336b61b938833fe011bda4a2001) file. Kirill owns this file and it acts as the source of truth for what metrics we are tracking for Mozilla Social. This shared [`metrics.yaml`](https://gist.github.com/kirill-demtchouk/41a38336b61b938833fe011bda4a2001) file is intended to be used by all the client teams - web, android & iOS. However, since there are some things in the `metrics.yaml` file that aren't applicable to web and other things that web needs that the other clients don't, there are some deviations to keep in mind. Keeping the `metrics.yaml` file up to date and with the correct client-specific info is a manual process currently. We need to figure out a better solution for this long-term but for the sake of getting everyone up to speed on where we are currently, I wanted to throw something together quickly. @@ -15,56 +13,22 @@ When this file has been updated, Kirill will notify us and we need to make chang 1. Copy the raw JSON of Kirill's `metrics.yaml` [gist](https://gist.github.com/kirill-demtchouk/41a38336b61b938833fe011bda4a2001) 2. Paste that raw JSON in the [`metrics.yaml`](./metrics.yaml) file here in elk, replacing everything that was there before 3. Check git diff to make sure I understand what is changing between the previous version and this one -4. Add back the things that the shared [`metrics.yaml`](https://gist.github.com/kirill-demtchouk/41a38336b61b938833fe011bda4a2001) file removes - - [Add lifetime parameter back](#add-lifetime-parameter-back-to-metrics-that-arent-events) - - [Add `no_lint` for baseline pings](#add-no_lint-for-baseline-pings) -5. Remove the extra things in the shared [`metrics.yaml`](https://gist.github.com/kirill-demtchouk/41a38336b61b938833fe011bda4a2001) file that aren't specific to web - - [Remove uneeded metrics](#remove-metrics-not-needed-for-web) -6. Now that we've added back all the things that we need for web and removed the extraneous details that we don't need, we need to make sure that all the new additions and removals that we are trying to incorporate from the shared [`metrics.yaml`]() file are included here in elk's [`metric.yaml`](./metrics.yaml) file -7. Run the `build:glean` script -8. Delete any old generated files (if needed) - 8a. If a category gets removed from the `metrics.yaml` file, glean does not automatically remove the old corresponding generated file, so we need to do that manually - -## Web-specific `metrics.yaml` file information +4. Remove the extra things in the shared [`metrics.yaml`](https://gist.github.com/kirill-demtchouk/41a38336b61b938833fe011bda4a2001) file that aren't specific to web + - [Remove unneeded metrics](#remove-metrics-not-needed-for-web) +5. Run the `build:glean` script +6. Delete any old generated files (if needed) + - If a category gets removed from the `metrics.yaml` file, glean does not automatically remove the old corresponding generated file, so we need to do that manually ### Remove metrics not needed for web 1. In the `identifiers` category: - - remove `fxa_account_id` - the elk client doesn't get the FxA ID back during auth, only a token so we will never have this - remove `adjust_device_id` - mobile specific -2. Remove the `backend` category - - the whole thing, including the `object_updated` metric - -### Add lifetime parameter back to metrics that aren't events - -For the events with a type other than `event`, we need to include the `lifetime: application` parameter to make it so that these metrics show up with every ping. - -For example: - -``` yaml -mastodon_account_id: - type: string - lifetime: application # lifetime added back here - ... -``` - -Note: Aly & Daniel are to sync up on this and try to figure out if there's a different way to accomplish this without using `lifetime: application`. But for now, make sure these are added back when updating the `metrics.yaml` file. - -### Add `no_lint` for baseline pings - -Some of the metrics in the shared [`metrics.yaml`](https://gist.github.com/kirill-demtchouk/41a38336b61b938833fe011bda4a2001) file include `baseline` in the `send_in_pings` parameter. If we keep this, the `build:glean` script will fail to build. Rather than removing it, we have opted for adding a `no_lint` declaration instead. - -For every metric that includes `baseline` in the `send_in_pings`, update it to be this instead: - -``` yaml -send_in_pings: - - events -no_lint: - - baseline # baseline removed from `send_in_pings, added `no_lint` -``` +2. Remove `baseline` everywhere it exists +3. Remove the `backend` category + - the whole thing, including the `object_updated` metric ## The Spreadsheet™️ -The data team has requested that we keep [this spreadsheet](https://docs.google.com/spreadsheets/d/1KX6TiyXXg2fE0a1IDKsy5O97ZrHYvjKohmIX_m8ECXY/edit#gid=1532914466) up to date as we add engagement events. It's very similar to what we were doing in pocket - tracking the engagement event name and all its corresponding additional details. +The data team has requested that we keep [this spreadsheet](https://docs.google.com/spreadsheets/d/1KX6TiyXXg2fE0a1IDKsy5O97ZrHYvjKohmIX_m8ECXY/edit#gid=1532914466) up to date as we add engagement events. It's very similar to what we were doing in Pocket - tracking the event name and all its corresponding additional metadata. diff --git a/telemetry/generated/identifiers.ts b/telemetry/generated/identifiers.ts index 334bced402..2ebf94249f 100644 --- a/telemetry/generated/identifiers.ts +++ b/telemetry/generated/identifiers.ts @@ -6,9 +6,31 @@ import StringMetricType from "@mozilla/glean/private/metrics/string"; +/** + * The user's FxA account ID, if available. + * data_taxonomy: + * data_categories: [user.unique_id] + * data_uses: [analytics.reporting, personalize.content] + * data_subjects: [customer] + * data_qualifier: [identified] + * + * Generated from `identifiers.fxa_account_id`. + */ +export const fxaAccountId = new StringMetricType({ + category: "identifiers", + name: "fxa_account_id", + sendInPings: ["events"], + lifetime: "application", + disabled: false, +}); + /** * The user's full account handle, with domain. For example, * `account_name@mozilla.social`. + * data_taxonomy: + * data_categories: [user.account.username] + * data_uses: [analytics.reporting, personalize.content] + * data_subjects: [customer] * * Generated from `identifiers.mastodon_account_handle`. */ @@ -22,6 +44,11 @@ export const mastodonAccountHandle = new StringMetricType({ /** * The user's numeric account ID from Mastodon. + * data_taxonomy: + * data_categories: [user.unique_id] + * data_uses: [analytics.reporting, personalize.content] + * data_subjects: [customer] + * data_qualifier: [identified] * * Generated from `identifiers.mastodon_account_id`. */ @@ -35,6 +62,11 @@ export const mastodonAccountId = new StringMetricType({ /** * The device user agent string. + * data_taxonomy: + * data_categories: [user.device] + * data_uses: [analytics.reporting] + * data_subjects: [customer, visitor] + * data_qualifier: [n/a] * * Generated from `identifiers.user_agent`. */ diff --git a/telemetry/generated/ui.ts b/telemetry/generated/ui.ts index 55f6e02126..36e61cb43f 100644 --- a/telemetry/generated/ui.ts +++ b/telemetry/generated/ui.ts @@ -9,6 +9,11 @@ import EventMetricType from "@mozilla/glean/private/metrics/event"; /** * Event triggered when a user taps/clicks on a UI element, triggering a change in * app state. + * data_taxonomy: + * data_categories: [user.behavior] + * data_uses: [analytics.reporting, personalize.content] + * data_subjects: [customer, visitor] + * data_qualifier: [n/a] * * Generated from `ui.engagement`. */ @@ -33,6 +38,11 @@ export const engagement = new EventMetricType<{ * Event triggered when a user views a notable UI element. Triggered once per page * load, as soon as any pixel of that UI element is visible in the foreground for * any length of time. UI elements may include: content, pages, CTAs, etc. + * data_taxonomy: + * data_categories: [user.behavior] + * data_uses: [analytics.reporting, personalize.content] + * data_subjects: [customer, visitor] + * data_qualifier: [n/a] * * Generated from `ui.impression`. */ diff --git a/telemetry/generated/web.ts b/telemetry/generated/web.ts index 289bd9518d..e74ffb308c 100644 --- a/telemetry/generated/web.ts +++ b/telemetry/generated/web.ts @@ -4,11 +4,16 @@ // AUTOGENERATED BY glean_parser v8.1.1. DO NOT EDIT. DO NOT COMMIT. -import StringMetricType from "@mozilla/glean/private/metrics/string"; import EventMetricType from "@mozilla/glean/private/metrics/event"; +import StringMetricType from "@mozilla/glean/private/metrics/string"; /** * Event triggered when a user clicks a link on a web page. + * data_taxonomy: + * data_categories: [user.behavior] + * data_uses: [analytics.reporting] + * data_subjects: [customer, visitor] + * data_qualifier: [n/a] * * Generated from `web.link_click`. */ @@ -26,6 +31,11 @@ export const linkClick = new EventMetricType<{ /** * The full URL of the page that was visited, along with URL query parameters. For * example, `https://mozilla.social/home?utm_source=test`. + * data_taxonomy: + * data_categories: [user.behavior.browsing_history] + * data_uses: [analytics.reporting] + * data_subjects: [customer, visitor] + * data_qualifier: [n/a] * * Generated from `web.page_url`. */ @@ -39,6 +49,11 @@ export const pageUrl = new StringMetricType({ /** * Event triggered when a user requests to load a web page. + * data_taxonomy: + * data_categories: [user.behavior] + * data_uses: [analytics.reporting] + * data_subjects: [customer, visitor] + * data_qualifier: [n/a] * * Generated from `web.page_view`. */ @@ -52,8 +67,13 @@ export const pageView = new EventMetricType({ /** * The full URL of the previous web page from which a link was followed in order - * to trigger the page view. Comes from the `referer` field of the HTTP header. + * to trigger the page view. Comes from the `referrer` field of the HTTP header. * May not always be available. For example, `https://www.google.com`. + * data_taxonomy: + * data_categories: [] + * data_uses: [analytics.reporting] + * data_subjects: [customer, visitor] + * data_qualifier: [n/a] * * Generated from `web.referrer_url`. */ diff --git a/telemetry/metrics.yaml b/telemetry/metrics.yaml index 05e5d91a40..2f1031305b 100644 --- a/telemetry/metrics.yaml +++ b/telemetry/metrics.yaml @@ -1,57 +1,89 @@ $schema: moz://mozilla.org/schemas/glean/metrics/2-0-0 identifiers: - mastodon_account_id: + fxa_account_id: # not used by web, but requested by Kirill to keep in here type: string + description: > + The user's FxA account ID, if available. + + data_taxonomy: + data_categories: [user.unique_id] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer] + data_qualifier: [identified] + bugs: + - https://mozilla-hub.atlassian.net/browse/MSDO-49 + data_reviews: + - https://docs.google.com/document/d/17vK3r7Sihb_S4-_8oKNoAraWeb_QiomC3UL-2W7PHgY/edit?usp=sharing + notification_emails: + - kdemtchouk@mozilla.com lifetime: application + expires: never + send_in_pings: + - events + + mastodon_account_id: + type: string description: > The user's numeric account ID from Mastodon. + + data_taxonomy: + data_categories: [user.unique_id] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer] + data_qualifier: [identified] bugs: - - TBD + - https://mozilla-hub.atlassian.net/browse/MSDO-49 data_reviews: - - TBD + - https://docs.google.com/document/d/17vK3r7Sihb_S4-_8oKNoAraWeb_QiomC3UL-2W7PHgY/edit?usp=sharing notification_emails: - kdemtchouk@mozilla.com + lifetime: application expires: never send_in_pings: - events - no_lint: - - baseline mastodon_account_handle: type: string - lifetime: application description: > The user's full account handle, with domain. For example, `account_name@mozilla.social`. + + data_taxonomy: + data_categories: [user.account.username] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer] bugs: - - TBD + - https://mozilla-hub.atlassian.net/browse/MSDO-49 data_reviews: - - TBD + - https://docs.google.com/document/d/17vK3r7Sihb_S4-_8oKNoAraWeb_QiomC3UL-2W7PHgY/edit?usp=sharing notification_emails: - kdemtchouk@mozilla.com + lifetime: application expires: never send_in_pings: - events - no_lint: - - baseline user_agent: type: string - lifetime: application description: > The device user agent string. + + data_taxonomy: + data_categories: [user.device] + data_uses: [analytics.reporting] + data_subjects: [customer, visitor] + data_qualifier: [n/a] bugs: - - TBD + - https://mozilla-hub.atlassian.net/browse/MSDO-49 data_reviews: - - TBD + - https://docs.google.com/document/d/17vK3r7Sihb_S4-_8oKNoAraWeb_QiomC3UL-2W7PHgY/edit?usp=sharing notification_emails: - kdemtchouk@mozilla.com + lifetime: application expires: never send_in_pings: - events - no_lint: - - baseline ui: impression: @@ -61,10 +93,16 @@ ui: Triggered once per page load, as soon as any pixel of that UI element is visible in the foreground for any length of time. UI elements may include: content, pages, CTAs, etc. + + data_taxonomy: + data_categories: [user.behavior] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer, visitor] + data_qualifier: [n/a] bugs: - - TBD + - https://mozilla-hub.atlassian.net/browse/MSDO-49 data_reviews: - - TBD + - https://docs.google.com/document/d/17vK3r7Sihb_S4-_8oKNoAraWeb_QiomC3UL-2W7PHgY/edit?usp=sharing notification_emails: - kdemtchouk@mozilla.com expires: never @@ -77,17 +115,35 @@ ui: increasing order of specificity (e.g. `[SCREEN].[BUTTON]`). All existing identifier values are being tracked here: https://docs.google.com/spreadsheets/d/1KX6TiyXXg2fE0a1IDKsy5O97ZrHYvjKohmIX_m8ECXY/edit?usp=sharing + + data_taxonomy: + data_categories: [system.operations] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer, visitor] + data_qualifier: [n/a] type: string ui_additional_detail: &ui_additional_detail description: > - An optional string to record further informatin about the UI + An optional string to record further information about the UI element, such as its starting value if it is a toggle or setting. + + data_taxonomy: + data_categories: [system.operations, personalize.content] + data_uses: [analytics.reporting] + data_subjects: [customer, visitor] + data_qualifier: [n/a] type: string mastodon_status_id: &mastodon_status_id description: > The Mastodon status ID of the post that was seen/interacted with by the user, if any. The Mastodon API calls statuses "posts", but they are one and the same. + + data_taxonomy: + data_categories: [user.behavior.browsing_history] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer, visitor] + data_qualifier: [n/a] type: string mastodon_account_id: &mastodon_account_id description: > @@ -95,6 +151,12 @@ ui: with by the user, if any. For example, the account ID of the user who created a post that was seen/interacted with. Or, the account ID of the user that was followed. + + data_taxonomy: + data_categories: [user.behavior.browsing_history] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer, visitor] + data_qualifier: [n/a] type: string mastodon_account_handle: &mastodon_account_handle description: > @@ -102,11 +164,23 @@ ui: with by the user, if any. For example, the account handle of the user who created a post that was seen/interacted with. Or, the account handle of the user that was followed. + + data_taxonomy: + data_categories: [user.behavior.browsing_history] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer, visitor] + data_qualifier: [n/a] type: string recommendation_id: &recommendation_id description: > TBD recommendation identifier of the content that was seen/interacted with by the user, if any. + + data_taxonomy: + data_categories: [user.behavior.browsing_history] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer, visitor] + data_qualifier: [n/a] type: string engagement: @@ -114,10 +188,16 @@ ui: description: > Event triggered when a user taps/clicks on a UI element, triggering a change in app state. + + data_taxonomy: + data_categories: [user.behavior] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer, visitor] + data_qualifier: [n/a] bugs: - - TBD + - https://mozilla-hub.atlassian.net/browse/MSDO-49 data_reviews: - - TBD + - https://docs.google.com/document/d/17vK3r7Sihb_S4-_8oKNoAraWeb_QiomC3UL-2W7PHgY/edit?usp=sharing notification_emails: - kdemtchouk@mozilla.com expires: never @@ -138,47 +218,72 @@ ui: * `favorite` * `boost` * `bookmark` + * `share` * `general` + + data_taxonomy: + data_categories: [user.behavior] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer, visitor] + data_qualifier: [n/a] type: string engagement_value: description: > If the UI element is a toggle or setting, the value of the toggle/setting after user interaction has taken place. + + data_taxonomy: + data_categories: [system.operations] + data_uses: [analytics.reporting, personalize.content] + data_subjects: [customer, visitor] + data_qualifier: [n/a] type: string web: page_url: type: string - lifetime: application description: > The full URL of the page that was visited, along with URL query parameters. For example, `https://mozilla.social/home?utm_source=test`. + + data_taxonomy: + data_categories: [user.behavior.browsing_history] + data_uses: [analytics.reporting] + data_subjects: [customer, visitor] + data_qualifier: [n/a] bugs: - - TBD + - https://mozilla-hub.atlassian.net/browse/MSDO-49 data_reviews: - - TBD + - https://docs.google.com/document/d/17vK3r7Sihb_S4-_8oKNoAraWeb_QiomC3UL-2W7PHgY/edit?usp=sharing notification_emails: - kdemtchouk@mozilla.com + lifetime: application expires: never send_in_pings: - events referrer_url: type: string - lifetime: application description: > The full URL of the previous web page from which a link was followed in order to trigger the page view. - Comes from the `referer` field of the HTTP header. + Comes from the `referrer` field of the HTTP header. May not always be available. For example, `https://www.google.com`. + + data_taxonomy: + data_categories: [] + data_uses: [analytics.reporting] + data_subjects: [customer, visitor] + data_qualifier: [n/a] bugs: - - TBD + - https://mozilla-hub.atlassian.net/browse/MSDO-49 data_reviews: - - TBD + - https://docs.google.com/document/d/17vK3r7Sihb_S4-_8oKNoAraWeb_QiomC3UL-2W7PHgY/edit?usp=sharing notification_emails: - kdemtchouk@mozilla.com + lifetime: application expires: never send_in_pings: - events @@ -187,10 +292,16 @@ web: type: event description: > Event triggered when a user requests to load a web page. + + data_taxonomy: + data_categories: [user.behavior] + data_uses: [analytics.reporting] + data_subjects: [customer, visitor] + data_qualifier: [n/a] bugs: - - TBD + - https://mozilla-hub.atlassian.net/browse/MSDO-49 data_reviews: - - TBD + - https://docs.google.com/document/d/17vK3r7Sihb_S4-_8oKNoAraWeb_QiomC3UL-2W7PHgY/edit?usp=sharing notification_emails: - kdemtchouk@mozilla.com expires: never @@ -199,10 +310,16 @@ web: type: event description: > Event triggered when a user clicks a link on a web page. + + data_taxonomy: + data_categories: [user.behavior] + data_uses: [analytics.reporting] + data_subjects: [customer, visitor] + data_qualifier: [n/a] bugs: - - TBD + - https://mozilla-hub.atlassian.net/browse/MSDO-49 data_reviews: - - TBD + - https://docs.google.com/document/d/17vK3r7Sihb_S4-_8oKNoAraWeb_QiomC3UL-2W7PHgY/edit?usp=sharing notification_emails: - kdemtchouk@mozilla.com expires: never @@ -210,8 +327,20 @@ web: target_url: description: > The destination URL of the link that the user clicked. + + data_taxonomy: + data_categories: [user.behavior.browsing_history] + data_uses: [analytics.reporting] + data_subjects: [customer, visitor] + data_qualifier: [n/a] type: string element_id: description: > The HTML element ID of the link that the user clicked. + + data_taxonomy: + data_categories: [] + data_uses: [analytics.reporting] + data_subjects: [customer, visitor] + data_qualifier: [n/a] type: string