From 7465581eb221ad7a7112c027f6ab04cda4b8edae Mon Sep 17 00:00:00 2001 From: Abed Fayyad Date: Tue, 24 Feb 2026 12:37:03 -0500 Subject: [PATCH 1/9] Clarify README for stewards --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 2f08872..215869e 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,12 @@ Contains the metrics.yaml file documenting the metrics collected by the Unified Used by https://github.com/mozilla-services/mars +## Additional Context for Data Stewards + +* The Unified API (MARS) uses Glean for **server-side** data collection. +* Telemetry is collected through MARS to measure ad performance and effectiveness. +* Users cannot opt out of specific metrics – data collection is tied to ad usage. Users who disable ads entirely have no ad-related telemetry collected. + ## Making Changes to Collected Data > At Mozilla, like at many other organizations, we rely on data to make product decisions. But here, unlike many other organizations, we balance our goal of collecting useful, high-quality data with our goal to give users meaningful choice and control over their own data. The Mozilla data collection program was created to ensure we achieve both goals whenever we make a change to how we collect data in our products. From 4045b9a3325bdff35feab754d1e674a3d857546b Mon Sep 17 00:00:00 2001 From: Masha Lifshin Date: Wed, 11 Mar 2026 18:00:21 -0700 Subject: [PATCH 2/9] Add more background and links on mars data collection --- README.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 52 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 215869e..c697a7c 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,63 @@ # mars-telemetry -Contains the metrics.yaml file documenting the metrics collected by the Unified API. +This repo contains the yaml files specifying the metrics collected by the Mozilla Ads Routing Service (MARS). -Used by https://github.com/mozilla-services/mars +[MARS repo](https://github.com/mozilla-services/mars ) -## Additional Context for Data Stewards +[MARS Glean dictionary](https://dictionary.telemetry.mozilla.org/apps/ads_backend) -* The Unified API (MARS) uses Glean for **server-side** data collection. -* Telemetry is collected through MARS to measure ad performance and effectiveness. -* Users cannot opt out of specific metrics – data collection is tied to ad usage. Users who disable ads entirely have no ad-related telemetry collected. +# Background -## Making Changes to Collected Data +MARS is a backend API service that functions as a privacy-preserving proxy bewteen Firefox and third party ad providers. + +MARS handles requests for ads from the Firefox browser, processes them to redact or anonymize our users' information, forwards along these anonymized requests to third party ad providers, and returns privacy-respecting, tracker-free ads to Firefox. + +Some examples of these ads are the Sponsored Shortcuts and Sponsored Stories found on Firefox's Home and New Tab. + +An example of how MARS functions to preserve user privacy: +* Instead of passing the Firefox user's potentially fingerprintable User Agent string to ad partners, MARS sends along only the user's OS and whether they are on Desktop, Tablet, or Phone. The ad partner gets enough information to return an ad appropriate for the device, but has no way to identify, fingerprint, or track any user. + +# Data Collection in MARS with Glean + +MARS is a stateless service and doesn't collect or store any data itself. The only data it persists is via Glean ping to Mozilla's data warehouse. MARS also plays a privacy-preserving proxy role between Firefox users and our own data warehouse. + +## Necessary data + +MARS needs to collect some anonymized, agreggated data about user interactions with ads in order to do business with our third party ad partners and advertisers, and for our financial record keeping. This is because we are paid based on these interactions, for example by how many times we show an ad, or by how many times an ad gets clicked. This is Category 2 "Interaction" data, captured via our [interaction ping](https://dictionary.telemetry.mozilla.org/apps/ads_backend/pings/interaction). + +MARS also collects some anonymized, agreggated data to ensure our systems are functioning correctly and our third party partners are meeting their contractual obligations. This is Category 1 "Technical" data, captured via our [request-stats](https://dictionary.telemetry.mozilla.org/apps/ads_backend/pings/request-stats) and [provider-request-stats](https://dictionary.telemetry.mozilla.org/apps/ads_backend/pings/provider-request-stats) pings. + +## Server-side Glean + +MARS's Glean integration is server-side, and all our pings are sent without any of the `client_info.*` fields that would be populated in a typical client-side Glean integration. This means no client info ever gets sent by default. Instead we pick a few coarse, non-identifying client fields to include for necessary reporting, and place them under [the `ad_client` category](https://dictionary.telemetry.mozilla.org/apps/ads_backend?page=1&search=ad_client.) of the ping's metrics. + +## Opt-out + +At Mozilla we always give users meaningful choice and control over data collection. To opt-out of Mozilla Ads data collection, a user must opt out of ads entirely by going to Preferences > Home and unchecking "Support Firefox", or unchecking both "Sponsored shortcuts" and "Sponsored stories". + +This is because we invoice our third party ad partners and advertisers based on this data. So if we are showing ads, it is necessary to keep anonymized, agreggated data about user interactions with ads, for doing business and for our financial record keeping. + +## Preventing Persistent Identifiers + +Firefox clients that use MARS are required to send `ContextId`, a UUID, with their ad requests. The `ContextId` is used to enable features like users blocking specific ads they don't want to see again. The `ContextId` is one of the metrics we send in Glean pings and store under the `ad_client.` category. + +Clients of the MARS API are required to rotate their `ContextId`s at least every 3 days to prevent it from becoming a persistent identifier within our data warehouse. + +## Data Deletion + +MARS is currently a stateless service, we do not store any data on the users' behalf. The only data we store is the Category 1 and Category 2 data that we send in our Glean pings. This data is necessary to retain for our business purposes, so we do not provide a way for users to delete it. + +However, MARS does have a `/delete_user` endpoint set up, so if in the future we decided to store data on users' behalf, we have a mechanism ready that Firefox clients can use to give users the controls to delete their data. + +# Making Changes to Collected Data > At Mozilla, like at many other organizations, we rely on data to make product decisions. But here, unlike many other organizations, we balance our goal of collecting useful, high-quality data with our goal to give users meaningful choice and control over their own data. The Mozilla data collection program was created to ensure we achieve both goals whenever we make a change to how we collect data in our products. [*Data Collection at Mozilla*](https://wiki.mozilla.org/Data_Collection) -Making changes to our data collection practices requires additional review by a Data Steward. +Making changes to the metrics and pings in this repo requires review by a Data Steward, in addition to the usual Ads Engineering code review. + +## Data Steward Review 1. Submit your PR to `mars-telemetry` (but do **not** merge it yet!) 2. Fill out a [data collection review form](https://github.com/mozilla/data-review/blob/main/request.md) ([examples](https://bugzilla.mozilla.org/show_bug.cgi?id=1900898) [here](https://bugzilla.mozilla.org/show_bug.cgi?id=2006440)). @@ -24,4 +65,6 @@ Making changes to our data collection practices requires additional review by a 4. Add a comment to your PR linking your Bugzilla request and a copy of your proposed measurements table (from the data collection review form). 5. Send a friendly message to [#data-stewardship-help](https://mozilla.enterprise.slack.com/archives/C07LMRQ5Q6B) to request a review. Make sure to give some brief context on the change, and include a link to the PR and Bugzilla request. -Please note that any data collection modifications involving category 3 or 4 data will also need to follow the [Sensitive Data Collection Review Process](https://wiki.mozilla.org/Data_Collection#Step_3:_Sensitive_Data_Collection_Review_Process) outlined in the Data Collection wiki page. +## Sensitive Data Review + +If the data collection changes involve Category 3 or Category 4 data, or if it is initially unclear which Category the data might fall under, then the change will also need a [Sensitive Data Collection Review](https://wiki.mozilla.org/Data_Collection#Step_3:_Sensitive_Data_Collection_Review_Process), as outlined in the Data Collection wiki page. From 32b49a125b908928a925e2d733f594dfcbd6fa2e Mon Sep 17 00:00:00 2001 From: Masha Lifshin Date: Thu, 12 Mar 2026 10:28:13 -0700 Subject: [PATCH 3/9] Add referencing the README to instructions for data review requests --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c697a7c..8d9acae 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ Making changes to the metrics and pings in this repo requires review by a Data S 2. Fill out a [data collection review form](https://github.com/mozilla/data-review/blob/main/request.md) ([examples](https://bugzilla.mozilla.org/show_bug.cgi?id=1900898) [here](https://bugzilla.mozilla.org/show_bug.cgi?id=2006440)). 3. Submit the request to Bugzilla. 4. Add a comment to your PR linking your Bugzilla request and a copy of your proposed measurements table (from the data collection review form). -5. Send a friendly message to [#data-stewardship-help](https://mozilla.enterprise.slack.com/archives/C07LMRQ5Q6B) to request a review. Make sure to give some brief context on the change, and include a link to the PR and Bugzilla request. +5. Send a friendly message to [#data-stewardship-help](https://mozilla.enterprise.slack.com/archives/C07LMRQ5Q6B) to request a review. Make sure to give some brief context on the change, and include a link to the PR and Bugzilla request. Also include a link to this `README.md` for our reviewer to reference if they need context or background on MARS data collection. ## Sensitive Data Review From 332e3b65e00643dc2229d7d69409f2ca86cb8cd9 Mon Sep 17 00:00:00 2001 From: Masha Lifshin Date: Tue, 17 Mar 2026 17:26:09 -0700 Subject: [PATCH 4/9] Clarify concept of users vs context ids in the Data Deletion section --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8d9acae..1635a90 100644 --- a/README.md +++ b/README.md @@ -45,9 +45,9 @@ Clients of the MARS API are required to rotate their `ContextId`s at least every ## Data Deletion -MARS is currently a stateless service, we do not store any data on the users' behalf. The only data we store is the Category 1 and Category 2 data that we send in our Glean pings. This data is necessary to retain for our business purposes, so we do not provide a way for users to delete it. +MARS is currently a stateless service, we do not store any data on the users' behalf, nor have any way to identify clients or users, aside from the ephemeral `ContextId` detailed above. The only data we store is the Category 1 and Category 2 data that we send in our Glean pings. This data is necessary to retain for our business purposes, so we do not provide a way for users to delete it. -However, MARS does have a `/delete_user` endpoint set up, so if in the future we decided to store data on users' behalf, we have a mechanism ready that Firefox clients can use to give users the controls to delete their data. +However, MARS does have a `/delete_user` endpoint set up, so if in the future we decided to store data on users' behalf, we have a mechanism ready that Firefox clients can use to give users the controls to delete their data. This mechanism would still only use `ContextId` as the ephemeral identifier. By design, MARS cannot identify all past data for a particular user, only data associated with `ContextId`s passed by the client. So in this hypothetical future we can also periodically delete all data associated with old `ContextId`s. # Making Changes to Collected Data From 34fd6011a22f8f3241c02b4675a13802ad43e08a Mon Sep 17 00:00:00 2001 From: Masha Lifshin Date: Thu, 19 Mar 2026 12:45:23 -0700 Subject: [PATCH 5/9] Fix spelling of aggregated --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 1635a90..498beee 100644 --- a/README.md +++ b/README.md @@ -23,9 +23,9 @@ MARS is a stateless service and doesn't collect or store any data itself. The on ## Necessary data -MARS needs to collect some anonymized, agreggated data about user interactions with ads in order to do business with our third party ad partners and advertisers, and for our financial record keeping. This is because we are paid based on these interactions, for example by how many times we show an ad, or by how many times an ad gets clicked. This is Category 2 "Interaction" data, captured via our [interaction ping](https://dictionary.telemetry.mozilla.org/apps/ads_backend/pings/interaction). +MARS needs to collect some anonymized, aggregated data about user interactions with ads in order to do business with our third party ad partners and advertisers, and for our financial record keeping. This is because we are paid based on these interactions, for example by how many times we show an ad, or by how many times an ad gets clicked. This is Category 2 "Interaction" data, captured via our [interaction ping](https://dictionary.telemetry.mozilla.org/apps/ads_backend/pings/interaction). -MARS also collects some anonymized, agreggated data to ensure our systems are functioning correctly and our third party partners are meeting their contractual obligations. This is Category 1 "Technical" data, captured via our [request-stats](https://dictionary.telemetry.mozilla.org/apps/ads_backend/pings/request-stats) and [provider-request-stats](https://dictionary.telemetry.mozilla.org/apps/ads_backend/pings/provider-request-stats) pings. +MARS also collects some anonymized, aggregated data to ensure our systems are functioning correctly and our third party partners are meeting their contractual obligations. This is Category 1 "Technical" data, captured via our [request-stats](https://dictionary.telemetry.mozilla.org/apps/ads_backend/pings/request-stats) and [provider-request-stats](https://dictionary.telemetry.mozilla.org/apps/ads_backend/pings/provider-request-stats) pings. ## Server-side Glean @@ -35,7 +35,7 @@ MARS's Glean integration is server-side, and all our pings are sent without any At Mozilla we always give users meaningful choice and control over data collection. To opt-out of Mozilla Ads data collection, a user must opt out of ads entirely by going to Preferences > Home and unchecking "Support Firefox", or unchecking both "Sponsored shortcuts" and "Sponsored stories". -This is because we invoice our third party ad partners and advertisers based on this data. So if we are showing ads, it is necessary to keep anonymized, agreggated data about user interactions with ads, for doing business and for our financial record keeping. +This is because we invoice our third party ad partners and advertisers based on this data. So if we are showing ads, it is necessary to keep anonymized, aggregated data about user interactions with ads, for doing business and for our financial record keeping. ## Preventing Persistent Identifiers From c162a36e03e591442686345eb8158fb03d4b1479 Mon Sep 17 00:00:00 2001 From: Masha Lifshin Date: Thu, 19 Mar 2026 13:08:36 -0700 Subject: [PATCH 6/9] Reword to avoid implying MARS is receiving PII from Firefox --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 498beee..ba6cb10 100644 --- a/README.md +++ b/README.md @@ -8,13 +8,13 @@ This repo contains the yaml files specifying the metrics collected by the Mozill # Background -MARS is a backend API service that functions as a privacy-preserving proxy bewteen Firefox and third party ad providers. +Commonly in the ads industry, client apps or websites make requests for ads directly to ad servers. These direct requests allows ad partners to see a wealth of information, which can be used by ad partners to learn who is the specific person using an app or site, and to build profiles about that person across many different apps and websites. The ads returned and shown also commonly contain tracking code that detects a person's activities and adds to their profile. -MARS handles requests for ads from the Firefox browser, processes them to redact or anonymize our users' information, forwards along these anonymized requests to third party ad providers, and returns privacy-respecting, tracker-free ads to Firefox. +MARS is a backend API service that prevents ad partners from gaining this kind of information. It functions as a privacy-preserving proxy bewteen Firefox clients and third party ad providers. MARS takes requests for ads from the Firefox browser, redacts or anonymizes any information that can be used to identify users or create profiles, forwards along these anonymized requests to third party ad providers, and returns privacy-respecting, tracker-free ads to Firefox. Some examples of these ads are the Sponsored Shortcuts and Sponsored Stories found on Firefox's Home and New Tab. -An example of how MARS functions to preserve user privacy: +An example of one way MARS functions to preserve user privacy: * Instead of passing the Firefox user's potentially fingerprintable User Agent string to ad partners, MARS sends along only the user's OS and whether they are on Desktop, Tablet, or Phone. The ad partner gets enough information to return an ad appropriate for the device, but has no way to identify, fingerprint, or track any user. # Data Collection in MARS with Glean From 7ac896f283ce4b953f19030d4ead74027c8d648a Mon Sep 17 00:00:00 2001 From: Masha Lifshin Date: Fri, 20 Mar 2026 18:27:41 -0700 Subject: [PATCH 7/9] Reword for clarity --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ba6cb10..d7757b1 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This repo contains the yaml files specifying the metrics collected by the Mozill # Background -Commonly in the ads industry, client apps or websites make requests for ads directly to ad servers. These direct requests allows ad partners to see a wealth of information, which can be used by ad partners to learn who is the specific person using an app or site, and to build profiles about that person across many different apps and websites. The ads returned and shown also commonly contain tracking code that detects a person's activities and adds to their profile. +Commonly in the ads industry, client apps or websites make requests for ads directly to ad servers. These direct requests allows ad partners to see a wealth of information, which can be used to identify the specific person using an app or site, and to build profiles about that person across many different apps and sites. The ads returned and shown also commonly contain tracking code that detects that person's activities and adds to their profile. MARS is a backend API service that prevents ad partners from gaining this kind of information. It functions as a privacy-preserving proxy bewteen Firefox clients and third party ad providers. MARS takes requests for ads from the Firefox browser, redacts or anonymizes any information that can be used to identify users or create profiles, forwards along these anonymized requests to third party ad providers, and returns privacy-respecting, tracker-free ads to Firefox. From 8ba33a66fc0972c2c468596401e994ae58e70ea2 Mon Sep 17 00:00:00 2001 From: Masha Lifshin Date: Mon, 23 Mar 2026 12:05:11 -0700 Subject: [PATCH 8/9] Remove hypothetical future speculation about delete_user --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index d7757b1..cb33fa3 100644 --- a/README.md +++ b/README.md @@ -47,8 +47,6 @@ Clients of the MARS API are required to rotate their `ContextId`s at least every MARS is currently a stateless service, we do not store any data on the users' behalf, nor have any way to identify clients or users, aside from the ephemeral `ContextId` detailed above. The only data we store is the Category 1 and Category 2 data that we send in our Glean pings. This data is necessary to retain for our business purposes, so we do not provide a way for users to delete it. -However, MARS does have a `/delete_user` endpoint set up, so if in the future we decided to store data on users' behalf, we have a mechanism ready that Firefox clients can use to give users the controls to delete their data. This mechanism would still only use `ContextId` as the ephemeral identifier. By design, MARS cannot identify all past data for a particular user, only data associated with `ContextId`s passed by the client. So in this hypothetical future we can also periodically delete all data associated with old `ContextId`s. - # Making Changes to Collected Data > At Mozilla, like at many other organizations, we rely on data to make product decisions. But here, unlike many other organizations, we balance our goal of collecting useful, high-quality data with our goal to give users meaningful choice and control over their own data. The Mozilla data collection program was created to ensure we achieve both goals whenever we make a change to how we collect data in our products. From c1de9b296520618acfa5a49d516bbcd49a37123e Mon Sep 17 00:00:00 2001 From: Masha Lifshin Date: Mon, 23 Mar 2026 12:53:20 -0700 Subject: [PATCH 9/9] Final tweaks --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cb33fa3..6568ed5 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ This is because we invoice our third party ad partners and advertisers based on ## Preventing Persistent Identifiers -Firefox clients that use MARS are required to send `ContextId`, a UUID, with their ad requests. The `ContextId` is used to enable features like users blocking specific ads they don't want to see again. The `ContextId` is one of the metrics we send in Glean pings and store under the `ad_client.` category. +Firefox clients that use MARS are required to send `ContextId`, a UUID, with their ad requests. The `ContextId` is used to enable features like users blocking specific ads they don't want to see again. The `ContextId` is one of the metrics we send in Glean pings and store under the `ad_client.*` category. Clients of the MARS API are required to rotate their `ContextId`s at least every 3 days to prevent it from becoming a persistent identifier within our data warehouse. @@ -61,7 +61,10 @@ Making changes to the metrics and pings in this repo requires review by a Data S 2. Fill out a [data collection review form](https://github.com/mozilla/data-review/blob/main/request.md) ([examples](https://bugzilla.mozilla.org/show_bug.cgi?id=1900898) [here](https://bugzilla.mozilla.org/show_bug.cgi?id=2006440)). 3. Submit the request to Bugzilla. 4. Add a comment to your PR linking your Bugzilla request and a copy of your proposed measurements table (from the data collection review form). -5. Send a friendly message to [#data-stewardship-help](https://mozilla.enterprise.slack.com/archives/C07LMRQ5Q6B) to request a review. Make sure to give some brief context on the change, and include a link to the PR and Bugzilla request. Also include a link to this `README.md` for our reviewer to reference if they need context or background on MARS data collection. +5. Send a friendly message to [#data-stewardship-help](https://mozilla.enterprise.slack.com/archives/C07LMRQ5Q6B) to request a review. Make sure to: + * Give some brief context on the change + * Include a link to the PR and Bugzilla request + * Include a link to this `README.md` for our reviewer to reference for background on MARS data collection. ## Sensitive Data Review