RHIDP-1908: Documenting the telemetry feature in admin guide

assemblies/assembly-rhdh-telemetry.adoc

@@ -0,0 +1,33 @@
+[id="assembly-rhdh-telemetry_{context}"]
+= Telemetry data collection
+
+The telemetry data collection feature is disabled by default. {product} sends telemetry data to Red Hat by using the `backstage-plugin-analytics-provider-segment` plugin.
+
+[IMPORTANT]
+====
+You can disable the telemetry data collection feature based on your needs. For example, in an air-gapped environment, you can disable this feature to avoid needless outbound requests affecting the responsiveness of the {product-very-short} application. For more details, see the link:{LinkAdminGuide}#disabling-telemetry-data-collection_admin-rhdh[Disabling telemetry data collection in {product-very-short}] section.
+====
+
+{company-name} analyzes the collected data to understand your interactions with the {product-very-short} application without disclosing your identity and compromising your privacy. {company-name} uses the collected data only for internal analysis and to improve the offerings and your experience with {product}.
+
+This feature collects the following data about your {product-very-short} usage:
+
+* Events of page visits and clicks on links or buttons.
+* System-related information, for example, locale, timezone, user agent including browser and OS details.
+* Page-related information, for example, title, category, extension name, URL, path, referrer, and search parameters.
+
+IP address and username are anonymized to maintain your privacy:
+
+* The IP addresses are anonymized and recorded as `0.0.0.0`.
+* The usernames are recorded as an anonymized hash.   
+
+The username hash is a unique identifier that is used solely to identify the number of unique users of the {product-very-short} application.
+
+With {product-very-short}, you can customize the telemetry data collection feature and the telemetry Segment source configuration based on your needs.
+
+include::modules/admin/proc-disabling-telemetry.adoc[leveloffset=+1]
+
+include::modules/admin/proc-enabling-telemetry.adoc[leveloffset=+1]
+
+include::modules/admin/proc-customizing-telemetry-segment.adoc[leveloffset=+1]
+

modules/admin/proc-customizing-telemetry-segment.adoc

@@ -0,0 +1,49 @@
+[id="customizing-telemetry-segment_{context}"]
+= Customizing telemetry Segment source
+
+
+The `analytics-provider-segment` plugin sends the collected telemetry data to {company-name} by default. However, you can configure a new Segment source that receives telemetry data based on your needs. For configuration, you need a unique Segment write key that points to the Segment source.
+
+[NOTE]
+====
+By configuring a new Segment source, you can collect and analyze the same set of data that is mentioned in the link:{LinkAdminGuide}#assembly-rhdh-telemetry_admin-rhdh[Telemetry data collection] section. You might also require to create your own telemetry data collection notice for your application users.
+====
+
+.Procedure
+
+. Configure integration with your Segment source by using one of the following options:
++
+.Using Helm Chart
+
+* Add the following YAML code in your Helm configuration file:
++
+[source,yaml]
+----
+# ...
+upstream:
+  backstage:
+    extraEnvVars:
+      - name: SEGMENT_WRITE_KEY
+        value: <segment_key> # <1>
+# ...        
+----
+<1> `<segment_key>` denotes a unique identifier for your Segment source. 
+
++
+.Using the Operator
+
+* Add the following YAML code in your `Backstage` custom resource (CR):
++
+[source,yaml]
+----
+# ...
+extraEnvs:
+  envs:
+    - name: SEGMENT_WRITE_KEY
+      value: <segment_key> # <1>
+# ...
+----
+<1> `<segment_key>` denotes a unique identifier for your Segment source. 
+
+. Save the configuration changes.
+

modules/admin/proc-disabling-telemetry.adoc

@@ -0,0 +1,66 @@
+[id="disabling-telemetry-data-collection_{context}"]
+= Disabling telemetry data collection in {product-very-short}
+
+To disable telemetry data collection, you must disable the `analytics-provider-segment` plugin either using the Helm Chart or the {product} Operator configuration. 
+
+[NOTE]
+====
+If the `analytics-provider-segment` plugin is already present in your dynamic plugins configuration, set the value of the `plugins.disabled` parameter to `true` to disable telemetry data collection.
+====
+
+.Procedure
+
+. Disable the `analytics-provider-segment` plugin by using one of the following options:
++
+.Using Helm Chart
+
+* Add the following YAML code in your Helm configuration file:
++
+[source,yaml]
+----
+# ...
+global:
+  dynamic:
+    plugins:
+      - package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment'
+        disabled: true
+# ...
+----
+
++
+.Using the Operator
+
+.. Perform one of the following steps:
++
+* If you have created the `dynamic-plugins-rhdh` ConfigMap file, add the `analytics-provider-segment` plugin to the list of plugins and set its `plugins.disabled` parameter to `true`.
++
+* If you have not created the ConfigMap file, create it with the following YAML code:
++
+[source,yaml]
+----
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: dynamic-plugins-rhdh
+data:
+  dynamic-plugins.yaml: |
+    includes:
+      - dynamic-plugins.default.yaml
+    plugins:
+      - package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment'
+        disabled: true
+----
+
+.. Set the value of the `dynamicPluginsConfigMapName` parameter to the name of the ConfigMap file in your `Backstage` custom resource:
++
+[source,yaml]
+----
+# ...
+spec:
+  application:
+    dynamicPluginsConfigMapName: dynamic-plugins-rhdh
+# ...
+----
+
+. Save the configuration changes.
+

modules/admin/proc-enabling-telemetry.adoc

@@ -0,0 +1,65 @@
+[id="enabling-telemetry-data-collection_{context}"]
+= Enabling telemetry data collection in {product-very-short}
+
+The telemetry data collection feature is enabled by default. However, if you have disabled the feature and want to re-enable it, you must enable the `analytics-provider-segment` plugin either by using the Helm Chart or the {product} Operator configuration. 
+
+[NOTE]
+====
+If the `analytics-provider-segment` plugin is already present in your dynamic plugins configuration, set the value of the `plugins.disabled` parameter to `false` to enable telemetry data collection.
+====
+
+.Procedure
+
+. Configure the `analytics-provider-segment` plugin by using one of the following options:
++
+.Using Helm Chart
+
+* Add the following YAML code in your Helm configuration file:
++
+[source,yaml]
+----
+# ...
+global:
+  dynamic:
+    plugins:
+      - package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment'
+        disabled: false
+# ...
+----
+
++
+.Using the Operator
+
+.. Perform one of the following steps:
++
+* If you have created the `dynamic-plugins-rhdh` ConfigMap file, add the `analytics-provider-segment` plugin to the list of plugins and set its `plugins.disabled` parameter to `false`.
++
+* If you have not created the ConfigMap file, create it with the following YAML code:
++
+[source,yaml]
+----
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: dynamic-plugins-rhdh
+data:
+  dynamic-plugins.yaml: |
+    includes:
+      - dynamic-plugins.default.yaml
+    plugins:
+      - package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment'
+        disabled: false        
+----
+
+.. Set the value of the `dynamicPluginsConfigMapName` parameter to the name of the ConfigMap file in your `Backstage` custom resource:
++
+[source,yaml]
+----
+# ...
+spec:
+  application:
+    dynamicPluginsConfigMapName: dynamic-plugins-rhdh
+# ...    
+----
+
+. Save the configuration changes.

titles/admin-rhdh/title-admin.adoc

@@ -18,6 +18,9 @@ include::assemblies/assembly-install-rhdh-ocp.adoc[leveloffset=+1]
 
 include::assemblies/assembly-enabling-authentication.adoc[leveloffset=+1]
 
+//Telemetry data collection
+include::assemblies/assembly-rhdh-telemetry.adoc[leveloffset=+1]
+
 //aws integration
 include::assemblies/assembly-rhdh-integration-aws.adoc[leveloffset=+1]