metrics: Add a mechanism to notify users when we want to collect additional metrics.

When we change the version number in metrics_utils:

If the user is not a Googler, or has opted out explicitly, nothing happens
and we still don't collect metrics.

If we're collecting metrics from the user, we stop collecting metrics
and display a notice telling them what has changed.
That notice will be displayed ten times, after which we will
resume collecting metrics. A notice telling them we're collecting metrics
will still be displayed.

Bug: None
Change-Id: If1cc12b2fc06f0d6237714c4f182367b1afdf9fb
Reviewed-on: https://chromium-review.googlesource.com/c/1285395
Commit-Queue: Edward Lesmes <ehmaldonado@chromium.org>
Reviewed-by: Andrii Shyshkalov <tandrii@chromium.org>

metrics.README.md

@@ -48,6 +48,13 @@ The metrics we're collecting are:
   - Are you setting `use\_relative\_paths=True`?
   - Are you using `recursedeps`?
 
+## Why am I seeing this message *again*?
+
+We might want to collect additional metrics, and if so we will ask you for
+permission again.
+
+Opting in or out explicitly will stop the messages from being displayed.
+
 # How can I check if metrics are being collected?
 
 You can run `gclient metrics` and it will report if you have opted in, out, or

metrics.py

@@ -69,6 +69,7 @@ class _Config(object):
     # safe values otherwise.
     self._config.setdefault('countdown', DEFAULT_COUNTDOWN)
     self._config.setdefault('opt-in', None)
+    self._config.setdefault('version', metrics_utils.CURRENT_VERSION)
 
     if config != self._config:
       print(INVALID_CONFIG_WARNING, file=sys.stderr)
@@ -83,6 +84,11 @@ class _Config(object):
       print(PERMISSION_DENIED_WARNING % e, file=sys.stderr)
       self._config['opt-in'] = False
 
+  @property
+  def version(self):
+    self._ensure_initialized()
+    return self._config['version']
+
   @property
   def is_googler(self):
     self._ensure_initialized()
@@ -97,6 +103,7 @@ class _Config(object):
   def opted_in(self, value):
     self._ensure_initialized()
     self._config['opt-in'] = value
+    self._config['version'] = metrics_utils.CURRENT_VERSION
     self._write_config()
 
   @property
@@ -104,13 +111,34 @@ class _Config(object):
     self._ensure_initialized()
     return self._config['countdown']
 
+  @property
+  def should_collect_metrics(self):
+    # Don't collect the metrics unless the user is a googler, the user has opted
+    # in, or the countdown has expired.
+    if not self.is_googler:
+      return False
+    if self.opted_in is False:
+      return False
+    if self.opted_in is None and self.countdown > 0:
+      return False
+    return True
+
   def decrease_countdown(self):
     self._ensure_initialized()
     if self.countdown == 0:
       return
     self._config['countdown'] -= 1
+    if self.countdown == 0:
+      self._config['version'] = metrics_utils.CURRENT_VERSION
     self._write_config()
 
+  def reset_config(self):
+    # Only reset countdown if we're already collecting metrics.
+    if self.should_collect_metrics:
+      self._ensure_initialized()
+      self._config['countdown'] = DEFAULT_COUNTDOWN
+      self._config['opt-in'] = None
+
 
 class MetricsCollector(object):
   def __init__(self):
@@ -198,10 +226,7 @@ class MetricsCollector(object):
       # file.
       if DISABLE_METRICS_COLLECTION:
         return func
-      # Don't collect the metrics unless the user is a googler, the user has
-      # opted in, or the countdown has expired.
-      if (not self.config.is_googler or self.config.opted_in == False
-          or (self.config.opted_in is None and self.config.countdown > 0)):
+      if not self.config.should_collect_metrics:
         return func
       # Otherwise, collect the metrics.
       # Needed to preserve the __name__ and __doc__ attributes of func.
@@ -236,6 +261,13 @@ class MetricsCollector(object):
       elif not isinstance(exception[1], SystemExit):
         traceback.print_exception(*exception)
 
+    # Check if the version has changed
+    if (not DISABLE_METRICS_COLLECTION and self.config.is_googler
+        and self.config.opted_in is not False
+        and self.config.version != metrics_utils.CURRENT_VERSION):
+      metrics_utils.print_version_change(self.config.version)
+      self.config.reset_config()
+
     # Print the notice
     if (not DISABLE_METRICS_COLLECTION and self.config.is_googler
         and self.config.opted_in is None):

metrics_utils.py

@@ -12,8 +12,16 @@ import sys
 from third_party import colorama
 
 
+# Current version of metrics recording.
+# When we add new metrics, the version number will be increased, we display the
+# user what has changed, and ask the user to agree again.
+CURRENT_VERSION = 0
+
 APP_URL = 'https://cit-cli-metrics.appspot.com'
 
+EMPTY_LINE = (
+  '*                                                   *'
+)
 NOTICE_COUNTDOWN_HEADER = (
   '*****************************************************\n'
   '*  METRICS COLLECTION WILL START IN %2d EXECUTIONS   *'
@@ -22,14 +30,23 @@ NOTICE_COLLECTION_HEADER = (
   '*****************************************************\n'
   '*      METRICS COLLECTION IS TAKING PLACE           *'
 )
+NOTICE_VERSION_CHANGE_HEADER = (
+  '*****************************************************\n'
+  '*       WE ARE COLLECTING ADDITIONAL METRICS        *'
+)
 NOTICE_FOOTER = (
-  '*                                                   *\n'
   '* For more information, and for how to disable this *\n'
   '* message, please see metrics.README.md in your     *\n'
   '* depot_tools checkout.                             *\n'
   '*****************************************************\n'
 )
 
+CHANGE_NOTICE = {
+  # No changes for version 0
+  0: '',
+}
+
+
 KNOWN_PROJECT_URLS = {
   'https://chrome-internal.googlesource.com/chrome/ios_internal',
   'https://chrome-internal.googlesource.com/infra/infra_internal',
@@ -105,9 +122,21 @@ def get_repo_timestamp(path_to_repo):
 def print_notice(countdown):
   """Print a notice to let the user know the status of metrics collection."""
   colorama.init()
-  print(colorama.Fore.RED + '\033[1m', file=sys.stderr)
+  print(colorama.Fore.RED + '\033[1m', file=sys.stderr, end='')
   if countdown:
     print(NOTICE_COUNTDOWN_HEADER % countdown, file=sys.stderr)
   else:
     print(NOTICE_COLLECTION_HEADER, file=sys.stderr)
+  print(EMPTY_LINE, file=sys.stderr)
   print(NOTICE_FOOTER + colorama.Style.RESET_ALL, file=sys.stderr)
+
+
+def print_version_change(config_version):
+  """Print a notice to let the user know we are collecting more metrics."""
+  colorama.init()
+  print(colorama.Fore.RED + '\033[1m', file=sys.stderr, end='')
+  print(NOTICE_VERSION_CHANGE_HEADER, file=sys.stderr)
+  print(EMPTY_LINE, file=sys.stderr)
+  for version in range(config_version + 1, CURRENT_VERSION + 1):
+    print(CHANGE_NOTICE[version], file=sys.stderr)
+    print(EMPTY_LINE, file=sys.stderr)