mobile/android/fenix/docs/Telemetry-implementation,-reviews,-renewals.md

   1 # Telemetry - Implementation, Reviews, Renewals
   2
   3 See https://github.com/mozilla-mobile/fenix/wiki/Telemetry-Checklist for the steps to implement new probes.
   4
   5 # Creating Glean Annotations
   6
   7 Glean Annotations repository: https://github.com/mozilla/glean-annotations
   8
   9 See [Add a Glean Annotation for an event](https://github.com/mozilla-mobile/fenix/wiki/Add-a-Glean-Annotation-for-an-event) for instructions.
  10
  11 More info [here](https://mozilla.github.io/glean-annotations/contributing/creating/)
  12
  13
  14 # Data review
  15
  16 Data reviews are needed on all PRs that add new telemetry or modify existing telemetry.
  17
  18 1. The implementer must complete the forms for [data renewal](https://github.com/mozilla/data-review/blob/main/renewal_request.md) or [a new data request](https://github.com/mozilla/data-review/blob/main/request.md) and put them as a comment in their PR.
  19 2. Once the form is complete, contact a [Data Steward](https://wiki.mozilla.org/Data_Collection) to arrange a review. Note: a data review does not replace code review! The PR should not land without both a data review and a code review.
  20 3. Once the data review is complete, add the link to the approval in the `data_reviews` sub-section of your metric in the `metrics.yaml` file.
  21 Example:
  22
  23 ```
  24 download_notification:
  25   resume:
  26     type: event
  27     description: |
  28       A user resumed a download in the download notification
  29     bugs:
  30       - https://github.com/mozilla-mobile/fenix/issues/5583
  31     data_reviews:
  32       - https://github.com/mozilla-mobile/fenix/pull/6554
  33       - https://github.com/mozilla-mobile/fenix/pull/13958#issuecomment-676857877
  34       - https://github.com/mozilla-mobile/fenix/pull/18143
  35     data_sensitivity:
  36       - interaction
  37     notification_emails:
  38       - fenix-core@mozilla.com
  39     expires: "2021-07-01"
  40 ```
  41
  42 When a telemetry probe is being renewed, do not remove the old data review links from `metrics.yaml`. The new approval should be added to the existing list.
  43
  44 Make sure you are selecting the correct Category of data that is being collected: https://wiki.mozilla.org/Data_Collection#Data_Collection_Categories
  45
  46 # Renewing existing telemetry
  47
  48 1. Collect a list of metrics from metrics.yaml file in Fenix that will be expiring in that month
  49   a. Currently compiling these in [this doc](https://docs.google.com/document/d/1NGlnTa9TPyTnd3ciUPbwujbITjkX8p8vJybXcZrrM2w/edit#)
  50   b. This should be done at least a few weeks prior to the events/metrics' expiration date
  51   c. Including metric name, original data review PR link, description (if it’s unclear from the name)
  52 2. Figure out the owner for each of the metrics (who needs to give the OK to renew/remove)
  53   a. Most renewals will need product approval
  54   b. Other approvals could come from the engineering team (e.g. `preferences.remote_debugging_enabled`), GV, App Services, Performance (e.g. `startup.timeline.framework_primary`), etc.
  55 3. Answer any open questions for the metric owners, and get approval from them to:
  56   a. Renew the metric (for how long? 6 months? 1 year?)
  57   b. Choose not to renew (but not delete)
  58   c. Choose to remove the metric
  59   d. Renew the metric and set to never expire (this should only be for business critical metrics)
  60 4. Fill out the [renewal request](https://github.com/mozilla/data-review/blob/main/renewal_request.md) for each metric, with question 3 (“Why was the initial period of collection insufficient?”) being answered by the owner
  61 5. Open a PR for the renewals
  62   a. Sometimes it’s easier to split up the renewals into multiple PRs if there are multiple owners: e.g. [product renewals](https://github.com/mozilla-mobile/fenix/pull/21788), [perf renewals](https://github.com/mozilla-mobile/fenix/pull/21315), [Fission renewals](https://github.com/mozilla-mobile/fenix/pull/21779) for December 2021
  63 6. Get a data review for your [renewal request](https://github.com/mozilla/data-review/blob/main/renewal_request.md) and update each of the metrics’ data-reviews in metrics.yaml to reflect this
  64
  65 ## Approval process
  66
  67 For each telemetry probe that we want to renew, the data-review will ask us [these questions](https://github.com/mozilla/data-review/blob/main/renewal_request.md). Each probe/group of related probes should have answers to those questions ([example](https://github.com/mozilla-mobile/fenix/pull/20517#issuecomment-887038794)).
  68
  69 ### Example renewal data request
  70 ```
  71 # Request for Data Collection Renewal
  72
  73 `search_shortcuts:`
  74  selected
  75 1) Provide a link to the initial Data Collection Review Request for this collection.
  76 - https://github.com/mozilla-mobile/fenix/pull/1202#issuecomment-476870449
  77 - https://github.com/mozilla-mobile/fenix/pull/15713#issuecomment-703972068
  78 - https://github.com/mozilla-mobile/fenix/pull/19924#issuecomment-861423789
  79
  80 2) When will this collection now expire? 08/01/2022
  81 3) Why was the initial period of collection insufficient?
  82 Important for revenue tracking and optimization.
  83
  84 `Toolbar_settings:`
  85  changed_position:
  86 1) Provide a link to the initial Data Collection Review Request for this collection.
  87 - https://github.com/mozilla-mobile/fenix/pull/6608
  88 - https://github.com/mozilla-mobile/fenix/pull/15713#issuecomment-703972068
  89 - https://github.com/mozilla-mobile/fenix/pull/19924#issuecomment-861423789
  90
  91 2) When will this collection now expire? 08/01/2022
  92 3) Why was the initial period of collection insufficient?
  93 The data didn’t initially tell us what we wanted (there were bugs), so we want to continue tracking this so we can answer our questions.
  94
  95 `login_dialog:`
  96  displayed:
  97 cancelled
  98 saved
  99 never_save
 100 1) Provide a link to the initial Data Collection Review Request for this collection.
 101 - https://github.com/mozilla-mobile/fenix/pull/13050
 102 - https://github.com/mozilla-mobile/fenix/pull/19924#issuecomment-861423789
 103
 104 2) When will this collection now expire? 08/01/2022
 105 3) Why was the initial period of collection insufficient?
 106 Still need to optimize this feature and we want trends from 6+mo of data.
 107 ```
 108
 109 For product-defined telemetry, this will involve meeting with a product manager and discussing each probe. There are three options: renew the probe for another length of time (usually 6 months), let the probe expire to evaluate later if the probe is still needed, or remove the probe entirely.