Homebrew (opt-in) Analytics tweaks. (#57)

- add `HOMEBREW_PRODUCT` global variable
- only differentiate between `/usr/local` and `non-/usr/local` Homebrew
  prefixes to avoid sharing sensitive user information
- note if e.g. build errors are occurring under CI
- Add `HOMEBREW_NO_ANALYTICS` variable (this will be how people opt-out
  when this is enabled for everyone)
- Add `HOMEBREW_ANALYTICS_DEBUG` variable to output all the analytics
  that are sent
- Move Bash analytics code to `Library/Homebrew/utils/analytics.sh`
- Add documentation for our analytics and why/what/when/how and opt-out
- Only official Homebrew commands are reported
- Ruby analytics are now reported in a forked, background process

6 files changed, 123 insertions, 62 deletions

diff --git a/Library/Homebrew/cmd/tests.rb b/Library/Homebrew/cmd/tests.rb
index 19576ddd3..5ec841773 100644
--- a/Library/Homebrew/cmd/tests.rb
+++ b/Library/Homebrew/cmd/tests.rb
@@ -3,6 +3,7 @@ require "fileutils"
 module Homebrew
   def tests
     (HOMEBREW_LIBRARY/"Homebrew/test").cd do
+      ENV["HOMEBREW_NO_ANALYTICS"] = "1"
       ENV["TESTOPTS"] = "-v" if ARGV.verbose?
       ENV["HOMEBREW_NO_COMPAT"] = "1" if ARGV.include? "--no-compat"
       if ARGV.include? "--coverage"
diff --git a/Library/Homebrew/formula_installer.rb b/Library/Homebrew/formula_installer.rb
index c4462fd9d..da63b7b32 100644
--- a/Library/Homebrew/formula_installer.rb
+++ b/Library/Homebrew/formula_installer.rb
@@ -202,7 +202,10 @@ class FormulaInstaller
 
     oh1 "Installing #{Tty.green}#{formula.full_name}#{Tty.reset}" if show_header?
 
-    report_analytics_event("install", formula.full_name)
+    if formula.tap && !formula.tap.private?
+      options = effective_build_options_for(formula).used_options.to_a.join(" ")
+      report_analytics_event("install", "#{formula.full_name} #{options}".strip)
+    end
 
     @@attempted << formula
 
diff --git a/Library/Homebrew/global.rb b/Library/Homebrew/global.rb
index e6b7f7e5d..64ed1bf9e 100644
--- a/Library/Homebrew/global.rb
+++ b/Library/Homebrew/global.rb
@@ -12,6 +12,7 @@ require "rbconfig"
 
 ARGV.extend(HomebrewArgvExtension)
 
+HOMEBREW_PRODUCT = ENV["HOMEBREW_PRODUCT"]
 HOMEBREW_VERSION = ENV["HOMEBREW_VERSION"]
 HOMEBREW_WWW = "http://brew.sh"
 
diff --git a/Library/Homebrew/utils/analytics.rb b/Library/Homebrew/utils/analytics.rb
index 66be5696a..44e14dd1d 100644
--- a/Library/Homebrew/utils/analytics.rb
+++ b/Library/Homebrew/utils/analytics.rb
@@ -1,52 +1,66 @@
-
-def analytics_anonymous_prefix_and_os
+def analytics_label
   @analytics_anonymous_prefix_and_os ||= begin
-    "#{OS_VERSION}, #{HOMEBREW_PREFIX.to_s.gsub(ENV["HOME"], "~")}"
+    os = OS_VERSION
+    prefix = ", non-/usr/local" if HOMEBREW_PREFIX.to_s != "/usr/local"
+    ci = ", CI" if ENV["CI"]
+    "#{os}#{prefix}#{ci}"
   end
 end
 
-def report_analytics(type, metadata={})
+def report_analytics(type, metadata = {})
   return unless ENV["HOMEBREW_ANALYTICS"]
+  return if ENV["HOMEBREW_NO_ANALYTICS"]
 
-  metadata_args = metadata.map do |key, value|
-    ["-d", "#{key}=#{value}"] if key && value
-  end.compact.flatten
+  args = %W[
+    --max-time 3
+    --user-agent #{HOMEBREW_USER_AGENT_CURL}
+    -d v=1
+    -d tid=#{ENV["HOMEBREW_ANALYTICS_ID"]}
+    -d cid=#{ENV["HOMEBREW_ANALYTICS_USER_UUID"]}
+    -d aip=1
+    -d an=#{HOMEBREW_PRODUCT}
+    -d av=#{HOMEBREW_VERSION}
+    -d t=#{type}
+  ]
+  metadata.each { |k, v| args << "-d" << "#{k}=#{v}" if k && v }
 
-  # Send analytics. Anonymise the IP address (aip=1) and don't send or store
-  # any personally identifiable information.
+  # Send analytics. Don't send or store any personally identifiable information.
+  # https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics.md
   # https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide
   # https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters
-  system ENV["HOMEBREW_CURL"], "https://www.google-analytics.com/collect",
-    "-d", "v=1", "--silent", "--max-time", "3", "--output", "/dev/null",
-    "--user-agent", HOMEBREW_USER_AGENT_CURL,
-    "-d", "tid=#{ENV["HOMEBREW_ANALYTICS_ID"]}",
-    "-d", "cid=#{ENV["HOMEBREW_ANALYTICS_USER_UUID"]}",
-    "-d", "aip=1",
-    "-d", "an=Homebrew",
-    "-d", "av=#{HOMEBREW_VERSION}",
-    "-d", "t=#{type}",
-    *metadata_args
+  if ENV["HOMEBREW_ANALYTICS_DEBUG"]
+    puts Utils.popen_read ENV["HOMEBREW_CURL"],
+      "https://www.google-analytics.com/debug/collect",
+      *args
+  else
+    pid = fork do
+      exec ENV["HOMEBREW_CURL"],
+        "https://www.google-analytics.com/collect",
+        "--silent", "--output", "/dev/null",
+        *args
+    end
+    Process.detach pid
+  end
 end
 
-def report_analytics_event(category, action, label=analytics_anonymous_prefix_and_os, value=nil)
-  report_analytics(:event, {
+def report_analytics_event(category, action, label = analytics_label, value = nil)
+  report_analytics(:event,
     :ec => category,
     :ea => action,
     :el => label,
-    :ev => value,
-  })
+    :ev => value)
 end
 
-def report_analytics_exception(exception, options={})
-  if exception.is_a? BuildError
+def report_analytics_exception(exception, options = {})
+  if exception.is_a?(BuildError) &&
+     exception.formula.tap && !exception.formula.tap.private?
     report_analytics_event("BuildError", exception.formula.full_name)
   end
 
   fatal = options.fetch(:fatal, true) ? "1" : "0"
-  report_analytics(:exception, {
+  report_analytics(:exception,
     :exd => exception.class.name,
-    :exf => fatal,
-  })
+    :exf => fatal)
 end
 
 def report_analytics_screenview(screen_name)
diff --git a/Library/Homebrew/utils/analytics.sh b/Library/Homebrew/utils/analytics.sh
new file mode 100644
index 000000000..015a62ab3
--- /dev/null
+++ b/Library/Homebrew/utils/analytics.sh
@@ -0,0 +1,71 @@
+setup-analytics() {
+  [[ -z "$HOMEBREW_ANALYTICS" ]] && return
+  [[ -n "$HOMEBREW_NO_ANALYTICS" ]] && return
+
+  # User UUID file. Used for Homebrew user counting. Can be deleted and
+  # recreated with no adverse effect (beyond our user counts being inflated).
+  HOMEBREW_ANALYTICS_USER_UUID_FILE="$HOME/.homebrew_analytics_user_uuid"
+  if [[ -r "$HOMEBREW_ANALYTICS_USER_UUID_FILE" ]]
+  then
+    HOMEBREW_ANALYTICS_USER_UUID="$(<"$HOMEBREW_ANALYTICS_USER_UUID_FILE")"
+  else
+    HOMEBREW_ANALYTICS_USER_UUID="$(uuidgen)"
+    echo "$HOMEBREW_ANALYTICS_USER_UUID" > "$HOMEBREW_ANALYTICS_USER_UUID_FILE"
+  fi
+  export HOMEBREW_ANALYTICS_ID="UA-75654628-1"
+  export HOMEBREW_ANALYTICS_USER_UUID
+}
+
+report-analytics-screenview-command() {
+  if [[ -z "$HOMEBREW_ANALYTICS" || -n "$HOMEBREW_NO_ANALYTICS" ]]
+  then
+    return
+  fi
+
+  # Don't report non-official commands.
+  if ! [[ "$HOMEBREW_COMMAND" = "bundle"   ||
+          "$HOMEBREW_COMMAND" = "cask"     ||
+          "$HOMEBREW_COMMAND" = "services" ||
+          -f "$HOMEBREW_LIBRARY/Homebrew/cmd/$HOMEBREW_COMMAND.rb"     ||
+          -f "$HOMEBREW_LIBRARY/Homebrew/cmd/$HOMEBREW_COMMAND.sh"     ||
+          -f "$HOMEBREW_LIBRARY/Homebrew/dev-cmd/$HOMEBREW_COMMAND.rb" ||
+          -f "$HOMEBREW_LIBRARY/Homebrew/dev-cmd/$HOMEBREW_COMMAND.sh" ]]
+  then
+    return
+  fi
+
+  # Don't report commands used mostly by our scripts and not users.
+  # TODO: list more e.g. shell completion things here perhaps using a single
+  # script as a shell-completion entry point.
+  if [[ "$HOMEBREW_COMMAND" = "commands" ]]
+  then
+    return
+  fi
+
+  local args=(
+    --max-time 3 \
+    --user-agent "$HOMEBREW_USER_AGENT_CURL" \
+    -d v=1 \
+    -d tid="$HOMEBREW_ANALYTICS_ID" \
+    -d cid="$HOMEBREW_ANALYTICS_USER_UUID" \
+    -d aip=1 \
+    -d an="$HOMEBREW_PRODUCT" \
+    -d av="$HOMEBREW_VERSION" \
+    -d t=screenview \
+    -d cd="$HOMEBREW_COMMAND" \
+  )
+
+  # Send analytics. Don't send or store any personally identifiable information.
+  # https://github.com/Homebrew/brew/blob/master/share/doc/homebrew/Analytics.md
+  # https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide#screenView
+  # https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters
+  if [[ -z "$HOMEBREW_ANALYTICS_DEBUG" ]]
+  then
+    "$HOMEBREW_CURL" https://www.google-analytics.com/collect \
+      "${args[@]}" \
+      --silent --output /dev/null &>/dev/null & disown
+  else
+    "$HOMEBREW_CURL" https://www.google-analytics.com/debug/collect \
+      "${args[@]}"
+  fi
+}
diff --git a/Library/brew.sh b/Library/brew.sh
index 96ee3bd91..3bb15adb4 100644
--- a/Library/brew.sh
+++ b/Library/brew.sh
@@ -111,6 +111,7 @@ export HOMEBREW_VERSION
 export HOMEBREW_CELLAR
 export HOMEBREW_RUBY_PATH
 export HOMEBREW_CURL
+export HOMEBREW_PRODUCT
 export HOMEBREW_OS_VERSION
 export HOMEBREW_OSX_VERSION
 export HOMEBREW_USER_AGENT
@@ -196,39 +197,9 @@ EOS
   esac
 fi
 
-if [[ -n "$HOMEBREW_ANALYTICS" ]]
-then
-  # User UUID file. Used for Homebrew user counting. Can be deleted and
-  # recreated with no adverse effect (beyond our user counts being inflated).
-  HOMEBREW_ANALYTICS_USER_UUID_FILE="$HOME/.homebrew_analytics_user_uuid"
-  if [[ -r "$HOMEBREW_ANALYTICS_USER_UUID_FILE" ]]
-  then
-    HOMEBREW_ANALYTICS_USER_UUID="$(<"$HOMEBREW_ANALYTICS_USER_UUID_FILE")"
-  else
-    HOMEBREW_ANALYTICS_USER_UUID="$(uuidgen)"
-    echo "$HOMEBREW_ANALYTICS_USER_UUID" > "$HOMEBREW_ANALYTICS_USER_UUID_FILE"
-  fi
-  export HOMEBREW_ANALYTICS_ID="UA-75654628-1"
-  export HOMEBREW_ANALYTICS_USER_UUID
-
-  # Send the to-be-executed command as an "App Screen View". Anonymise the IP
-  # address (aip=1) and don't send or store any personally identifiable
-  # information.
-  # https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide#screenView
-  # https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters
-  "$HOMEBREW_CURL" https://www.google-analytics.com/collect -d v=1 \
-    --silent --max-time 3 --output /dev/null \
-    --user-agent "$HOMEBREW_USER_AGENT_CURL" \
-    -d tid="$HOMEBREW_ANALYTICS_ID" \
-    -d cid="$HOMEBREW_ANALYTICS_USER_UUID" \
-    -d aip=1 \
-    -d an=Homebrew \
-    -d av="$HOMEBREW_VERSION" \
-    -d t=screenview \
-    -d cd="$HOMEBREW_COMMAND" \
-    &> /dev/null \
-    & disown
-fi
+source "$HOMEBREW_LIBRARY/Homebrew/utils/analytics.sh"
+setup-analytics
+report-analytics-screenview-command
 
 update-preinstall() {
   [[ -n "$HOMEBREW_AUTO_UPDATE" ]] || return