docs: rework telemetry doc and add CLI warning (#10354)

ammario · web-flow · commit b7990148323b · 2023-10-19T15:50:20.000-05:00
diff --git a/cli/server.go b/cli/server.go
@@ -782,6 +782,8 @@ func (r *RootCmd) Server(newAPI func(context.Context, *coderd.Options) (*coderd.
 					return xerrors.Errorf("create telemetry reporter: %w", err)
 				}
 				defer options.Telemetry.Close()
+			} else {
+				logger.Warn(ctx, `telemetry disabled, unable to notify of security issues. Read more: https://coder.com/docs/v2/latest/admin/telemetry`)
 			}
 
 			// This prevents the pprof import from being accidentally deleted.
diff --git a/docs/admin/telemetry.md b/docs/admin/telemetry.md
@@ -1,38 +1,44 @@
 # Telemetry
 
-Coder collects telemetry data from all free installations. Our users have the
-right to know what we collect, why we collect it, and how we use the data.
+<blockquote class="info">
+TL;DR: disable telemetry by setting <code>CODER_TELEMETRY=false</code>.
+</blockquote>
 
-## What we collect
+Coder collects telemetry from all installations by default. We believe our users
+should have the right to know what we collect, why we collect it, and how we use
+the data.
 
-First of all, we do not collect any information that could threaten the security
-of your installation. For example, we do not collect parameters, environment
-variables, or passwords.
+## What we collect
 
-You can find a full list of the data we collect in the source code
+You can find a full list of the data we collect in our source code
 [here](https://github.com/coder/coder/blob/main/coderd/telemetry/telemetry.go).
+In particular, look at the struct types such as `Template` or `Workspace`.
+
+As a rule, we **do not collect** the following types of information:
+
+- Any data that could make your installation less secure
+- Any data that could identify individual users
 
-Telemetry can be configured with the `CODER_TELEMETRY=x` environment variable.
+For example, we do not collect parameters, environment variables, or user email
+addresses.
 
-For example, telemetry can be disabled with `CODER_TELEMETRY=false`.
+## Why we collect
 
-`CODER_TELEMETRY=true` is our default level. It includes user email and IP
-addresses. This information is used in aggregate to understand where our users
-are and general demographic information. We may reach out to the deployment
-admin, but will never use these emails for outbound marketing.
+Telemetry helps us understand which features are most valuable, what use cases
+to focus on, and which bugs to fix first.
 
-`CODER_TELEMETRY=false` disables telemetry altogether.
+Most cloud-based software products collect far more data than we do. They often
+offer little transparency and configurability. It's hard to imagine our favorite
+SaaS products existing without their creators having a detailed understanding of
+user interactions. We want to wield some of that product development power to
+build self-hosted, open-source software.
 
-## How we use telemetry
+## Security
 
-We use telemetry to build product better and faster. Without telemetry, we don't
-know which features are most useful, we don't know where users are dropping off
-in our funnel, and we don't know if our roadmap is aligned with the demographics
-that really use Coder.
+In the event we discover a critical security issue with Coder, we will use
+telemetry to identify affected installations and notify their administrators.
 
-Typical SaaS companies collect far more than what we do with little transparency
-and configurability. It's hard to imagine our favorite products today existing
-without their backers having good intelligence.
+## Toggling
 
-We've decided the only way we can make our product open-source _and_ build at a
-fast pace is by collecting usage data as well.
+You can turn telemetry on or off using either the `CODER_TELEMETRY=[true|false]`
+environment variable or the `--telemetry=[true|false]` command-line flag.

Original file line number	Diff line number	Diff line change
`@@ -782,6 +782,8 @@ func (r RootCmd) Server(newAPI func(context.Context, coderd.Options) (*coderd.`
`782`	`782`	`return xerrors.Errorf("create telemetry reporter: %w", err)`
`783`	`783`	`}`
`784`	`784`	`defer options.Telemetry.Close()`
	`785`	`+ } else {`
	`786`	+ logger.Warn(ctx, `telemetry disabled, unable to notify of security issues. Read more: https://coder.com/docs/v2/latest/admin/telemetry`)
`785`	`787`	`}`
`786`	`788`
`787`	`789`	`// This prevents the pprof import from being accidentally deleted.`