Analytics documentation (#111)

- Add analytics collection documentation
- Improvement in the main README

README.md

@@ -22,7 +22,7 @@ Let's take the example of installing Kafka on a Kubernetes cluster. If you are a
 With kbrew, all of this happens with a "one step":
 
 ```
-$ kbrew install kafka-operator
+kbrew install kafka-operator
 ```
 
 Similarly when you install a Rook Ceph cluster - it makes it a `one step easy`:
@@ -60,6 +60,7 @@ Table of Contents
    * [Should I use kbrew for installing applications in a production environment?](#should-i-use-kbrew-for-installing-applications-in-a-production-environment)
    * [How can I contribute recipes for a project/tool?](#how-can-i-contribute-recipes-for-a-projecttool)
    * [How is analytics used?](#how-is-analytics-used)
+   * [What data is collected for analytics?](#what-data-is-collected-for-analytics)
    * [Who is developing kbrew?](#who-is-developing-kbrew)
 
 Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
@@ -80,28 +81,36 @@ While we are making it easy for users to install any application in one step, we
 
 ## Installation
 
+<details>
+   <summary>(Click to expand)</summary> 
+
 ### Install the pre-compiled binary
 
 ```bash
-$ curl -sfL https://raw.githubusercontent.com/kbrew-dev/kbrew/main/install.sh | sh
+export BINDIR=/usr/local/bin
+curl -sfL https://raw.githubusercontent.com/kbrew-dev/kbrew/main/install.sh | sh
 ```
 
 ### Compiling from source
 
 #### Step 1: Clone the repo
 
 ```bash
-$ git clone https://github.com/kbrew-dev/kbrew.git
+git clone https://github.com/kbrew-dev/kbrew.git
 ```
 
 #### Step 2: Build binary using make
 
 ```bash
-$ make
+make
 ```
-
+</details>
+
 ## CLI Usage
 
+<details>
+   <summary>(Click to expand)</summary> 
+
 ```
 $ kbrew --help
 A CLI tool for Kubernetes which makes installing any complex stack easy in one step.
@@ -152,6 +161,8 @@ Checks for kbrew updates and upgrades automatically if a newer version is availa
 
 Uninstalls the application and its dependencies.
 
+</details>
+
 ## Recipes
 
 A kbrew recipe is a YAML file that declares the installation process of a Kubernetes app. It allows to *brew* Helm charts or vanilla Kubernetes manifests with scripts, also managing dependencies with other recipes.
@@ -309,6 +320,10 @@ The recipes are maintained in [Kbrew registry](https://github.com/kbrew-dev/kbre
 
 The analytics is anonymized and used in aggregate to determine the failure/success rate of recipes and to improve user experience.
 
+##### What data is collected for analytics?
+
+Please check [analytics](docs/analytics.md) for details.
+
 ##### Who is developing kbrew?
 
 The team at [InfraCloud](https://www.infracloud.io/) is supporting Kbrew's development with love! But we love contributions from the community.

docs/analytics.md

@@ -0,0 +1,65 @@
+# Anonymous Aggregate Analytics
+
+kbrew gathers anonymous aggregate analytics using Google Analytics. The analytics are enabled by default but you can always [opt out](analytics.md#opting-out) and continue using kbrew without ever sending analytics data.
+
+## Why?
+The analytics is anonymized and used in aggregate to determine the failure/success rate of recipes and to improve user experience. It helps us understand how the tool is getting used and what we can do to make it even better.  Anonymous aggregate user analytics allows us to prioritize bug fixes, plan new features and design the roadmap. In the future, once we have enough data, we are planning to make the failure and success rates of the app installations public so that users can do install with confidence.
+
+## What?
+
+kbrew records the following events
+(ref: https://github.com/kbrew-dev/kbrew/blob/main/pkg/events/events.go#L97)
+
+| s/r | event  | example | 
+| --- |-------- | -------- |
+| 1 | kbrew [application name](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#an)     | `kbrew`  |
+| 2 | kbrew [application version](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#av)     | `v0.0.8`  |
+| 3 | [Google Analytics version](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#v)     | `1`  |
+| 4 | kbrew [analytics tracking ID](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#tid)     | `UA-xxxxxxx-1`  |
+| 5 | kbrew [analytics user ID](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#cid) | `c47d1a81-6cbe-4179-bdd1-4918e3be9768` (generated and stored after installation. See note for the details) |
+| 6 | [Google Analytics anonymous IP setting](https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#aip) | `1` (enabled)
+| 7 | kbrew [analytics hit type](h8tps://developers.google.com/analytics/devguides/collection/protocol/v1/parameters#t) | `event` |
+| 8 | K8s version of the cluster (on which kbrew installs app) | `v1.20.1` |
+| 9 | kbrew app name | `kafka` |
+| 10 | kbrew recipe args | `Deployment.nginx.spec.replicas: 4` |
+| 11 | kbrew error message | `Error rendering value: template: gotpl:1: unexpected {{end}}` |
+| 12 | kbrew event category | `install-fail` |
+
+**NOTE:**
+
+`kbrew analytics user ID` is generated by UUID generator when first time kbrew command is executed on a system and stored in the kbrew config `(${HOME}/.kbrew/config.yaml)` `analyticsuuid`. This does not allow us to track individual users but does enable us to accurately measure user counts versus event counts. The ID is specific to kbrew installation and does not permit kbrew maintainers to track anything else.
+
+On failures, kbrew also collects [the Kubernetes failure events](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#event-v1-core) generated for the recipe components. kbrew does not collect events on any other resources which are not created as a part of the installation. Kubernetes failure events help us tuning the recipes if it is not working in a specific environment.
+- K8s failure event reason
+- K8s failure event message
+- K8s failure event action
+- K8s failure event involvedObject 
+
+kbrew's analytics records the following different events:
+(ref: https://github.com/kbrew-dev/kbrew/blob/main/pkg/events/events.go#L45)
+
+- `install-success`: installation successful
+- `install-fail`: installation failed
+- `install-timeout`: installation timed out
+- `uninstall-success`: uninstallation successful
+- `uninstall-fail`: uninstallation failed
+- `uninstall-timeout`: uninstallation timed out
+- `k8s-event`: Kubernetes failure events sent after `install-fail` or `install-timeout` event
+
+
+It's practically impossible to map randomly generated user ID (UUID) with any particular event. So you don't have to worry about being tracked for the activity.
+
+## When/Where?
+kbrew analytics are sent throughout kbrew's execution to Google Analytics over HTTPS.
+
+## Opting out
+We appreciate keeping analytics on which helps us keep kbrew improving. But if you decided to opt-out of kbrew analytics, it can be disabled with
+
+```sh
+kbrew analytics off
+```
+The kbrew analytics status can be checked with 
+
+```sh
+kbrew analytics status
+```