Merge pull request #443 from ekinanp/analytics-docs

Update docs with analytics info

Author: MikaelSmith

docs/docs/index.html

@@ -91,6 +91,13 @@ <h1>Wash Documentation</h1>
 <li><a href="/wash/docs/core_plugins">➠Core Plugins</a></li>
 <li><a href="/wash/docs/api">➠Server API</a></li>
 </ul></li>
+<li><a href="#analytics">Analytics</a>
+
+<ul>
+<li><a href="#what-data-does-wash-collect">What data does Wash collect?</a></li>
+<li><a href="#why-does-wash-collect-data">Why does Wash collect data?</a></li>
+<li><a href="#how-can-i-opt-out-of-wash-data-collection">How can I opt out of Wash data collection?</a></li>
+</ul></li>
 </ul>
 
 <h2 id="wash-commands">Wash Commands</h2>
@@ -443,6 +450,43 @@ <h3 id="entry-schemas">Entry Schemas</h3>
 
 <p>Entry schemas are also useful for optimizing <code>find</code>, especially when <code>find</code> is used for metadata filtering. Without entry schemas, for example, an EC2 instance query like <code>find aws -meta '.tags[?]' .key termination_date</code> would cause <code>find</code> to recurse into every entry in the <code>aws</code> plugin, including non-EC2 instance entries like S3 objects. With entry schemas, however, <code>find</code> would only recurse into those entries that will eventually lead to an EC2 instance. The latter is a significantly faster (and less expensive) operation, especially for large infrastructures.</p>
 
+<h2 id="analytics">Analytics</h2>
+
+<p>Wash collects anonymous data about how you use it. You can opt out of providing this data.</p>
+
+<h3 id="what-data-does-wash-collect">What data does Wash collect?</h3>
+
+<ul>
+<li>Version of Wash</li>
+<li>User locale</li>
+<li>Architecture</li>
+<li>Method invocations (for core plugin entries only)
+
+<ul>
+<li>This includes any invocation of the <code>List</code>, <code>Exec</code>, <code>Read</code>, and <code>Stream</code> primitives</li>
+<li>Also includes the entry&rsquo;s plugin</li>
+</ul></li>
+</ul>
+
+<p>This data is associated with Bolt analytics&rsquo; UUID (if available); otherwise, the data is associated with a random, non-identifiable user UUID.</p>
+
+<h3 id="why-does-wash-collect-data">Why does Wash collect data?</h3>
+
+<p>Wash collects data to help us understand how it&rsquo;s being used and make decisions about how to improve it.</p>
+
+<h3 id="how-can-i-opt-out-of-wash-data-collection">How can I opt out of Wash data collection?</h3>
+
+<p>To disable the collection of analytics data add the following line to <code>~/.puppetlabs/wash/analytics.yaml</code>:</p>
+<div class="highlight"><div style="background-color:#fff;-moz-tab-size:4;-o-tab-size:4;tab-size:4">
+<table style="border-spacing:0;padding:0;margin:0;border:0;width:auto;overflow:auto;display:block;"><tr><td style="vertical-align:top;padding:0;margin:0;border:0;">
+<pre style="background-color:#fff;-moz-tab-size:4;-o-tab-size:4;tab-size:4"><span style="margin-right:0.4em;padding:0 0.4em 0 0.4em;color:#7f7f7f">1
+</span></pre></td>
+<td style="vertical-align:top;padding:0;margin:0;border:0;">
+<pre style="background-color:#fff;-moz-tab-size:4;-o-tab-size:4;tab-size:4">disabled: true</pre></td></tr></table>
+</div>
+</div>
+<p>You can also disable the collection of analytics data by setting the <code>WASH_DISABLE_ANALYTICS</code> environment variable to <code>true</code> before starting up the Wash daemon.</p>
+
 </article>
 
 

docs/index.html

@@ -102,6 +102,8 @@ <h2 id="getting-started">Getting started</h2>
 
 <p>At this point, if you haven&rsquo;t already, you should start some resources that Wash can actually introspect. Otherwise, as Han Solo would say, &ldquo;this is going to be a real short trip&rdquo;. So fire up some Docker containers, create some EC2 instances, toss some files into S3, launch a Kubernetes pod, etc. We&rsquo;ve also provided a <a href="#wash-by-example">guided tour</a> that includes a Docker application.</p>
 
+<p><strong>NOTE:</strong> Wash collects anonymous data about how you use it. See the <a href="/wash/docs#analytics">analytics docs</a> for more details.</p>
+
 <h3 id="known-issues">Known issues</h3>
 
 <p>Wash uses your system shell to provide the shell environment. It determines this using the SHELL environment variable or falls back to <code>/bin/sh</code>, so if you&rsquo;d like to specify a particular shell set the SHELL environment variable before starting Wash.</p>

website/content/_index.md

@@ -48,6 +48,8 @@ Wash is distributed as a single binary, and the only prerequisite is [`libfuse`]
 
 At this point, if you haven't already, you should start some resources that Wash can actually introspect. Otherwise, as Han Solo would say, "this is going to be a real short trip". So fire up some Docker containers, create some EC2 instances, toss some files into S3, launch a Kubernetes pod, etc. We've also provided a [guided tour](#wash-by-example) that includes a Docker application.
 
+**NOTE:** Wash collects anonymous data about how you use it. See the [analytics docs](/wash/docs#analytics) for more details.
+
 ### Known issues
 
 Wash uses your system shell to provide the shell environment. It determines this using the SHELL environment variable or falls back to `/bin/sh`, so if you'd like to specify a particular shell set the SHELL environment variable before starting Wash.

website/content/docs/_index.md

@@ -29,6 +29,10 @@ title= "Wash Documentation"
   * [➠External plugins]
   * [➠Core Plugins]
   * [➠Server API]
+* [Analytics](#analytics)
+  * [What data does Wash collect?](#what-data-does-wash-collect)
+  * [Why does Wash collect data?](#why-does-wash-collect-data)
+  * [How can I opt out of Wash data collection?](#how-can-i-opt-out-of-wash-data-collection)
 
 ## Wash Commands
 
@@ -293,4 +297,30 @@ docker
 
 Every node must have a label. The `[]` are printed for non-singleton nodes; they imply multiple instances of this thing. For example, `[container]` means that there will be multiple `container` instances under the `containers` directory. Similarly, `containers` means that there will be only one `containers` directory (i.e. that `containers` is a singleton). Singleton entries should typically use the entry's name as the label.
 
-Entry schemas are also useful for optimizing `find`, especially when `find` is used for metadata filtering. Without entry schemas, for example, an EC2 instance query like `find aws -meta '.tags[?]' .key termination_date` would cause `find` to recurse into every entry in the `aws` plugin, including non-EC2 instance entries like S3 objects. With entry schemas, however, `find` would only recurse into those entries that will eventually lead to an EC2 instance. The latter is a significantly faster (and less expensive) operation, especially for large infrastructures.
+Entry schemas are also useful for optimizing `find`, especially when `find` is used for metadata filtering. Without entry schemas, for example, an EC2 instance query like `find aws -meta '.tags[?]' .key termination_date` would cause `find` to recurse into every entry in the `aws` plugin, including non-EC2 instance entries like S3 objects. With entry schemas, however, `find` would only recurse into those entries that will eventually lead to an EC2 instance. The latter is a significantly faster (and less expensive) operation, especially for large infrastructures.
+
+## Analytics
+
+Wash collects anonymous data about how you use it. You can opt out of providing this data.
+
+### What data does Wash collect?
+* Version of Wash
+* User locale
+* Architecture
+* Method invocations (for core plugin entries only)
+  * This includes any invocation of the `List`, `Exec`, `Read`, and `Stream` primitives
+  * Also includes the entry's plugin
+
+This data is associated with Bolt analytics' UUID (if available); otherwise, the data is associated with a random, non-identifiable user UUID.
+
+### Why does Wash collect data?
+Wash collects data to help us understand how it's being used and make decisions about how to improve it.
+
+### How can I opt out of Wash data collection?
+To disable the collection of analytics data add the following line to `~/.puppetlabs/wash/analytics.yaml`:
+
+```
+disabled: true
+```
+
+You can also disable the collection of analytics data by setting the `WASH_DISABLE_ANALYTICS` environment variable to `true` before starting up the Wash daemon.