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

2 files changed, 113 insertions, 28 deletions

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
+}