397 Add doc for anonymous usage stats (#4104) (#4109)

* 397 Add doc for anonymous usage stats

* Specify exactly what usage statistics Pyroscope reports

* Add links to the anonymous usage statistics page

* Run "make reference-help"

---------

Co-authored-by: Aleksandar Petrov <8142643+aleks-p@users.noreply.github.com>
Co-authored-by: Christian Simon <simon@swine.de>
(cherry picked from commit 70a2dbd)

Co-authored-by: Kim Nylander <104772500+knylander-grafana@users.noreply.github.com>

Author: github-actions[bot]

cmd/pyroscope/help-all.txt.tmpl

@@ -1092,7 +1092,7 @@ Usage of ./pyroscope:
   -tracing.profiling-enabled
     	[experimental] Set to true to enable profiling integration.
   -usage-stats.enabled
-    	Enable anonymous usage reporting. (default true)
+    	Enable anonymous usage statistics collection. For more details about usage statistics, refer to https://grafana.com/docs/pyroscope/latest/configure-server/anonymous-usage-statistics-reporting/ (default true)
   -validation.enforce-labels-order
     	Enforce labels order optimization.
   -validation.max-label-names-per-series int

cmd/pyroscope/help.txt.tmpl

@@ -408,7 +408,7 @@ Usage of ./pyroscope:
   -tracing.enabled
     	Set to false to disable tracing. (default true)
   -usage-stats.enabled
-    	Enable anonymous usage reporting. (default true)
+    	Enable anonymous usage statistics collection. For more details about usage statistics, refer to https://grafana.com/docs/pyroscope/latest/configure-server/anonymous-usage-statistics-reporting/ (default true)
   -validation.enforce-labels-order
     	Enforce labels order optimization.
   -validation.max-label-names-per-series int

docs/sources/configure-server/anonymous-usage-statistics-reporting.md

@@ -0,0 +1,60 @@
+---
+
+description: Learn about Grafana Pyroscope anonymous usage statistics reporting
+menuTitle: Anonymous usage statistics reporting
+title: About Grafana Pyroscope anonymous usage statistics reporting
+weight: 30
+---
+
+# About Grafana Pyroscope anonymous usage statistics reporting
+
+Grafana Pyroscope includes a system that optionally and anonymously reports non-sensitive, non-personally identifiable information about the running Pyroscope cluster to a remote statistics server.
+Pyroscope maintainers use this anonymous information to learn more about how the open source community runs Pyroscope and what the Pyroscope team should focus on when working on the next features and documentation improvements.
+
+The anonymous usage statistics reporting is **enabled by default**.
+You can opt-out setting the CLI flag `-usage-stats.enabled=false` or its respective YAML configuration option.
+
+## The statistics server
+
+When usage statistics reporting is enabled, information is collected by a server that Grafana Labs runs. Statistics are collected at `https://stats.grafana.org`.
+
+## Which information is collected
+
+When the usage statistics reporting is enabled, Grafana Pyroscope collects the following information:
+
+- Information about the **Pyroscope cluster and version**:
+  - A unique, randomly-generated Pyroscope cluster identifier, such as `3749b5e2-b727-4107-95ae-172abac27496`.
+  - The timestamp when the anonymous usage statistics reporting was enabled for the first time, and the cluster identifier was created.
+  - The Pyroscope version, such as `1.13.1`.
+  - The Pyroscope branch, revision, and Golang version that was used to build the binary.
+- Information about the **environment** where Pyroscope is running:
+  - The operating system, such as `linux`.
+  - The architecture, such as `amd64`.
+  - The Pyroscope memory utilization and number of goroutines.
+  - The number of logical CPU cores available to the Pyroscope process.
+- Information about the Pyroscope **configuration**:
+  - The `-target` parameter value, such as `all` when running Pyroscope in monolithic mode.
+  - The `-storage.backend` value, such as `s3`.
+  - The `-distributor.replication-factor` value, such as `3`.
+- Information about the Pyroscope **cluster scale**:
+  - Distributor:
+    - Bytes received.
+    - Profiles received with breakdown by profile type and programming language.
+    - Profile sizes with breakdown by programming language.
+  - Ingester:
+    - Number of active tenants.
+
+
+{{< admonition type="note" >}}
+Pyroscope maintainers commit to keeping the list of tracked information updated over time, and reporting any change both via the CHANGELOG and the release notes.
+{{< /admonition >}}
+
+## Disable the anonymous usage statistics reporting
+
+If possible, we ask you to keep the usage reporting feature enabled and help us understand more about how the open source community runs Pyroscope.
+In case you want to opt-out from anonymous usage statistics reporting, set the CLI flag `-usage-stats.enabled=false` or change the following YAML configuration:
+
+```yaml
+analytics:
+  reporting_enabled: false
+```

docs/sources/configure-server/reference-configuration-parameters/index.md

@@ -288,10 +288,10 @@ self_profiling:
 # CLI flag: -auth.multitenancy-enabled
 [multitenancy_enabled: <boolean> | default = false]
 
-analytics:
-  # Enable anonymous usage reporting.
-  # CLI flag: -usage-stats.enabled
-  [reporting_enabled: <boolean> | default = true]
+# The analytics block configures usage statistics collection. For more details
+# about usage statistics, refer to [Anonymous usage statistics
+# reporting](../anonymous-usage-statistics-reporting)
+[analytics: <analytics>]
 
 # Prints the application banner at startup.
 # CLI flag: -config.show_banner
@@ -2532,4 +2532,15 @@ The `filesystem_storage_backend` block configures the usage of local file system
 [dir: <string> | default = "./data-shared"]
 ```
 
+### analytics
+
+The `analytics` block configures usage statistics collection. For more details about usage statistics, refer to [Anonymous usage statistics reporting](../anonymous-usage-statistics-reporting)
+
+```yaml
+# Enable anonymous usage statistics collection. For more details about usage
+# statistics, refer to
+# https://grafana.com/docs/pyroscope/latest/configure-server/anonymous-usage-statistics-reporting/
+# CLI flag: -usage-stats.enabled
+[reporting_enabled: <boolean> | default = true]
 ```
+

docs/sources/configure-server/reference-configuration-parameters/index.template

@@ -60,4 +60,3 @@ where `default_value` is the value to use if the environment variable is undefin
 
 {{ .ConfigFile }}
 
-```

docs/sources/get-started/_index.md

@@ -27,6 +27,12 @@ For more information on the different ways to deploy Pyroscope, see [Pyroscope d
 
 Verify that you have installed [Docker](https://docs.docker.com/engine/install/).
 
+{{< admonition type="note" >}}
+Pyroscope includes a system that optionally and anonymously reports non-sensitive, non-personally identifiable information about the running Pyroscope cluster to a remote statistics server to help Pyroscope maintainers understand how the open source community runs Pyroscope.
+
+To opt out, refer to [Disable the anonymous usage statistics reporting](../configure-server/anonymous-usage-statistics-reporting#disable-the-anonymous-usage-statistics-reporting).
+{{< /admonition >}}
+
 ## Download and configure Pyroscope
 
 1. Download Pyroscope.

pkg/usagestats/reporter.go

@@ -46,7 +46,7 @@ type Config struct {
 
 // RegisterFlags adds the flags required to config this to the given FlagSet
 func (cfg *Config) RegisterFlags(f *flag.FlagSet) {
-	f.BoolVar(&cfg.Enabled, "usage-stats.enabled", true, "Enable anonymous usage reporting.")
+	f.BoolVar(&cfg.Enabled, "usage-stats.enabled", true, "Enable anonymous usage statistics collection. For more details about usage statistics, refer to https://grafana.com/docs/pyroscope/latest/configure-server/anonymous-usage-statistics-reporting/")
 }
 
 type Reporter struct {

tools/doc-generator/parse/root_blocks.go

@@ -22,6 +22,7 @@ import (
 	"github.com/grafana/pyroscope/pkg/querier/worker"
 	"github.com/grafana/pyroscope/pkg/scheduler"
 	"github.com/grafana/pyroscope/pkg/storegateway"
+	"github.com/grafana/pyroscope/pkg/usagestats"
 	"github.com/grafana/pyroscope/pkg/validation"
 )
 
@@ -113,4 +114,9 @@ var RootBlocks = []RootBlock{
 		StructType: reflect.TypeOf(filesystem.Config{}),
 		Desc:       "The filesystem_storage_backend block configures the usage of local file system as object storage backend.",
 	},
+	{
+		Name:       "analytics",
+		StructType: reflect.TypeOf(usagestats.Config{}),
+		Desc:       "The analytics block configures usage statistics collection. For more details about usage statistics, refer to [Anonymous usage statistics reporting](../anonymous-usage-statistics-reporting)",
+	},
 }