[hab] Add lightweight analytics to hab CLI which is defaulted to opt-out.

[fnichol]

The hab command-line tool will optionally send anonymous usage data to Habitat's Google Analytics account. This is a strictly opt-in activity and no tracking will occur unless you respond affirmatively to the question during hab setup. If you do not use hab setup, no data will ever be sent.

We collect this data to help improve Habitat's user experience: for example, to know what tasks users are performing, and which ones they are having trouble with (e.g. mistyping command line arguments).

By anonymous we mean that all identifying information about you is removed before we send the data. This includes the removal of any information about what packages you are building, or what origins you are using. For example, if you were building the package yourname/yourapp, and you typed hab pkg build -k yourkey yourname/yourapp, the fact that you were performing the pkg build operation would be transmitted. Neither the name of the specific package you are building, nor the fact that you are using the yourkey key to sign that package would be transmitted.

Please do not hesitate to contact us if you have questions or concerns about the use of Google Analytics within the Habitat product.

Note that this module is highly documented, even inside functions with the intent of guiding a user through the implementation who may not necessarily be familiar with Rust code. Given the "must-not-impact-the-user" nature of this code, it tends to be much more explicit than regular, idiomatic Rust code. But at least you can see a lot of match expressions in action :)

Subcommand Invocations

The following is a complete list of all pre-selected commands which are reported:

• apply
• artifact upload
• config apply
• file upload
• origin key generate
• pkg build
• ring key generate
• service key generate
• studio build
• studio enter
• user key generate

Subcommands Which Attempt Submission of Events

The only time events will be sent to the Google Analytics API is when certain subcommands are invoked which require network access. These subcommands are:

• apply
• artifact upload
• config apply
• file upload
• install
• origin key upload
• pkg install

For all other subcommands, even those which report events, the event payload is saved to a cached file under the analytics cache directory (/hab/cache/analytics for a root user and $HOME/.hab/cache/analytics for a non-root user).

Event Data Breakdown

For each event that is reported, a set of information is bundled into the payload. Here is a breakdown of each key/value entry:

v=1

The Protocol Version which is currently only ever the integer value of 1.

tid=UA-XXXXXXX-X

The Track ID
which represents this product and is currently hard coded as "UA-6369228-7".

cid=f673faaf-6ba1-4e60-b819-e2d51e4ad6f1

The Client ID
which is a randomly generated UUID v4 and written into the system or user's analytics cache (/hab/cache/analytics/CLIENT_ID when the program is invoked as the root user and $HOME/.hab/analytics/CLIENT_ID when invoked by a non-root user). This is not intended to track individual users or systems, but rather show patterns of usage in aggregate. For example: "In general, users who generally start with hab studio enter tend to migrate to using hab pkg build over time".

t=event

The Hit Type. This value is hard coded as "event" as it is a required Google Analtyics field for all Hit Events.

aip=1

Enables Anonymize IP. This entry ensures that the sender's IP address will not be captured and will be anonymized. The value is hard coded as the integer 1.

an=hab

The Application Name of the program sending the event. For this program the value is currently hard coded as "hab".

av=0.6.0%2F20160604180457

The Application Version of the program sending the event. This version string will be the same value as reported when asking for the program's version on the command line. Note that this field may contain characters that must be percent encoded.

ds=cli--hab

The Data Source which represents the program which generated the event data. For this program the value is currently hardcoded as "cli--hab".

ec=invoke

The Event Category which corresponds to the type of event being sent. Currently there are only 2 possible values: "invoke" for subcommand invocations and "clierror" for CLI errors.

ea=hab--pkg--build

The Event Action which breaks down differently depending on the type of event. For subcommand invocations (where "ec=invoke"), the value is the subcommand invoked with no further arguments, options, or flags. Any spaces are replaced with a doubledash, as in: "hab--studio--enter" or "hab--artifact--upload". For CLI errors (where "ec=clierror"), the value is the type of CLI error followed by a double dash and terminated with the subcommand which was invoked (also containing no further arguments, options, or flags). As before any spaces in the subcommand are replaced with a double dash, as in: "InvalidSubcommand--hab-whoops".

User-Agent HTTP Header

A user agent string is also included in the HTTP/POST to the Google Analytics API it is of the form:

<PRODUCT>/<VERSION> (<TARGET>; <KERNEL_RELEASE>)

where:

• <PRODUCT>: is the provided product name. For this program the value is currently hard coded as "hab".
• <VERSION>: is the provided version string which may also include a release number. This is the same version obtained when running the help or version subcommands.
• <TARGET>: is the machine architecture and the kernel separated by a dash in lower case.
• <KERNEL_RELEASE>: is the kernel release string from uname.

For example:

hab/0.6.0/20160606153031 (x86_64-darwin; 14.5.0)

[thesentinels]

By analyzing the blame information on this pull request, we identified @metadave, @reset and @adamhjk to be potential reviewers

[fnichol]

Ready for review!

[adamhjk]

On it

[adamhjk]

This should be a different contact email - something in the habitat.sh domain.

[adamhjk]

This looks great. The code is easy to read, easy to grok, and you met your goal of having it be very well documented. Honestly, it's so legit and well documented that I'm tempted to include hab-sup events (opt-in only, of course).

[fnichol]

@adamhjk The code was set up so that if we ever added another program it wouldn't be the hardest thing to do and the events would be partitioned by CLI/app.

[fnichol]

Email updated, merge ready

[fnichol]

@thesentinels r+

[thesentinels]

📌 Commit 978ecc0 has been approved by fnichol

[thesentinels]

⌛ Testing commit 978ecc0 with merge 6d375f0...

[adamhjk]

[thesentinels]

☀️ Test successful - travis