Included images (#1028)

Reorganize Segment/Telemetry instructions into its own category

Reorganize Segment/Telemetry instructions into its own category

Reorganize Segment/Telemetry instructions into its own category

Reorganize Segment/Telemetry instructions into its own category

Reorganize Segment/Telemetry instructions into its own category

Author: pabel-rh

assemblies/assembly-rhdh-telemetry.adoc

@@ -1,5 +1,5 @@
 [id="assembly-rhdh-telemetry"]
-= Telemetry data collection
+= Telemetry data collection and analysis
 
 The telemetry data collection feature helps in collecting and analyzing the telemetry data to improve your experience with {product}. This feature is enabled by default.
 
@@ -10,32 +10,44 @@ As an administrator, you can disable the telemetry data collection feature based
 
 {company-name} collects and analyzes the following data:
 
+*Web Analytics (Segment)*
+
+Web Analytics tracks user behavior and interactions with {product}. Specifically, it tracks the following:
+
 * Events of page visits and clicks on links or buttons.
-* System-related information, for example, locale, timezone, user agent including browser and OS details.
+* System-related information, for example, locale, time zone, user agent including browser and OS details.
 * Page-related information, for example, title, category, extension name, URL, path, referrer, and search parameters.
 * Anonymized IP addresses, recorded as `0.0.0.0`.
 * Anonymized username hashes, which are unique identifiers 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.
+*System Observability (OpenTelemetry)*
+
+System Observability tracks the performance of the {product-very-short}. Specifically, it tracks the following:
+
+* Key system metrics such as CPU usage, memory usage, and other performance indicators.
+* Information about system components, such as the locale, timezone, and user agent (including details of the browser and operating system).
+* Traces and logs monitor system processes, allowing you to troubleshoot potential issues impacting the performance of {product-very-short}.
+
+With {product-very-short}, you can customize the _Web Analytics_ and _System Observability_ configuration based on your needs.
 
 
 // disabling telemetry
-include::modules/observe/ref-disabling-telemetry.adoc[leveloffset=+1]
+include::modules/observe/analytics/ref-disabling-telemetry.adoc[leveloffset=+1]
 
-include::modules/observe/proc-disabling-telemetry-using-operator.adoc[leveloffset=+2]
+include::modules/observe/analytics/proc-disabling-telemetry-using-operator.adoc[leveloffset=+2]
 
-include::modules/observe/proc-disabling-telemetry-using-helm.adoc[leveloffset=+2]
+include::modules/observe/analytics/proc-disabling-telemetry-using-helm.adoc[leveloffset=+2]
 
 // enabling telemetry
-include::modules/observe/ref-enabling-telemetry.adoc[leveloffset=+1]
+include::modules/observe/analytics/ref-enabling-telemetry.adoc[leveloffset=+1]
 
-include::modules/observe/proc-enabling-telemetry-using-operator.adoc[leveloffset=+2]
+include::modules/observe/analytics/proc-enabling-telemetry-using-operator.adoc[leveloffset=+2]
 
-include::modules/observe/proc-enabling-telemetry-using-helm.adoc[leveloffset=+2]
+include::modules/observe/analytics/proc-enabling-telemetry-using-helm.adoc[leveloffset=+2]
 
 // customizing telemetry segment source
-include::modules/observe/ref-customizing-telemetry-segment.adoc[leveloffset=+1]
+include::modules/observe/analytics/ref-customizing-telemetry-segment.adoc[leveloffset=+1]
 
-include::modules/observe/proc-customizing-telemetry-segment-using-operator.adoc[leveloffset=+2]
+include::modules/observe/analytics/proc-customizing-telemetry-segment-using-operator.adoc[leveloffset=+2]
 
-include::modules/observe/proc-customizing-telemetry-segment-using-helm.adoc[leveloffset=+2]
+include::modules/observe/analytics/proc-customizing-telemetry-segment-using-helm.adoc[leveloffset=+2]

images/rhdh-plugins-reference/active-users.jpg

@@ -1,5 +1,5 @@
 [id="proc-customizing-telemetry-segment-using-helm_{context}"]
-= Customizing telemetry Segment source using the Helm Chart
+= Customizing Segment source using the Helm Chart
 
 You can configure integration with your Segment source by using the Helm Chart.
 

images/rhdh-plugins-reference/adoption-insights-catalog-entities.jpg

@@ -1,5 +1,5 @@
 [id="proc-customizing-telemetry-segment-using-operator_{context}"]
-= Customizing telemetry Segment source using the Operator
+= Customizing Segment source using the Operator
 
 You can configure integration with your Segment source by using the Operator.
 

images/rhdh-plugins-reference/adoption-insights-daterange.jpg

@@ -14,4 +14,6 @@ The Adoption Insights dashboard in {product-short} includes the following cards:
 * *Top 3 templates*
 * *Top 3 techdocs*
 * *Top 3 plugins*
-* *Portal searches*
+* *Portal searches*
+
+image::rhdh-plugins-reference/adoption-insights.jpg[adoption insights]

images/rhdh-plugins-reference/adoption-insights.jpg

@@ -17,6 +17,8 @@ By default, the top three most viewed catalog entities are displayed.
 
 * Go to *Administration -> Adoption Insights* and click the *Down* arrow next to *3 rows* to change the number of displayed records.
 
+image::rhdh-plugins-reference/adoption-insights-catalog-entities.jpg[Catalog Entities dropdown]
+
 == Modifying the number of displayed records in Top 3 templates
 
 You can modify the number of records that are displayed in the *Top 3 templates* card. You can select any of the following number of records for display:

modules/observe/proc-customizing-telemetry-segment-using-helm.adoc renamed to modules/analytics/proc-customizing-telemetry-segment-using-helm.adoc

@@ -2,9 +2,11 @@
 [id="proc-setting-duration-of-data-metrics_{context}"]
 = Setting the duration of data metrics
 
-You can set the data metrics duration using any of the time ranges, such as *Last 28 days* (default), *Today*, *Last week*, *Last month*, *Last year*, or *Date range...*.
+You can set the data metrics duration using any of the time ranges, such as *Today*, *Last week*, *Last month*, *Last 28 days* (default), *Last year*, or *Date range...*.
 
 .Procedure
 
 . On the top of the screen, click the dropdown list to display the choices.
-. Select the duration choice for which you want to see the data metrics.
+. Select the duration choice for which you want to see the data metrics.
+
+image::rhdh-plugins-reference/adoption-insights-daterange.jpg[date range]

modules/observe/proc-customizing-telemetry-segment-using-operator.adoc renamed to modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc

@@ -10,6 +10,8 @@ The *Active users* card displays the total number of active users over a specifi
 
 *New users*: New users who have registered and logged into {product-short}
 
+image::rhdh-plugins-reference/active-users.jpg[active users]
+
 .Procedure
 
 * To view the list of active users in your Developer Hub instance, go to *Administration -> Adoption Insights*, see the Active users card. 

modules/observe/proc-disabling-telemetry-using-helm.adoc renamed to modules/analytics/proc-disabling-telemetry-using-helm.adoc

@@ -0,0 +1,42 @@
+[id="proc-customizing-telemetry-segment-using-helm_{context}"]
+= Customizing Segment source using the Helm Chart
+
+You can configure integration with your Segment source by using the Helm Chart.
+
+.Prerequisites
+
+* You have logged in as an administrator in the {ocp-short} web console.
+* You have installed {product} on {ocp-short} using the Helm Chart.
+
+.Procedure
+
+. In the *Developer* perspective of the {ocp-short} web console, go to the *Helm* view to see the list of Helm releases.
+. Click the *overflow* menu on the Helm release that you want to use and select *Upgrade*.
+. Use either the *Form* view or *YAML* view to edit the Helm configuration:
+** Using *Form view*
++
+.. Expand *Root Schema → Backstage Chart Schema → Backstage Parameters → Backstage container environment variables*.
+.. Click the *Add Backstage container environment variables* link.
+.. Enter the name and value of the Segment key.
++
+image::rhdh/segment-source-helm.png[]
+
+.. Click *Upgrade*.
+
+** Using *YAML view*
++
+.. Add the following YAML code in your Helm configuration file:
++
+[source,yaml]
+----
+# ...
+upstream:
+  backstage:
+    extraEnvVars:
+      - name: SEGMENT_WRITE_KEY
+        value: <segment_key> # <1>
+# ...
+----
+<1> Replace `<segment_key>` with a unique identifier for your Segment source.
+
+.. Click *Upgrade*.

modules/observe/proc-disabling-telemetry-using-operator.adoc renamed to modules/analytics/proc-disabling-telemetry-using-operator.adoc

@@ -0,0 +1,28 @@
+[id="proc-customizing-telemetry-segment-using-operator_{context}"]
+= Customizing Segment source using the Operator
+
+You can configure integration with your Segment source by using the Operator.
+
+.Prerequisites
+
+* You have logged in as an administrator in the {ocp-short} web console.
+* You have installed {product} on {ocp-short} using the Operator.
+
+.Procedure
+
+. Add the following YAML code in your `{product-custom-resource-type}` custom resource (CR):
++
+[source,yaml]
+----
+# ...
+spec:
+  application:
+    extraEnvs:
+      envs:
+        - name: SEGMENT_WRITE_KEY
+          value: <segment_key> # <1>
+# ...
+----
+<1> Replace `<segment_key>` with a unique identifier for your Segment source.
+
+. Save the configuration changes.

modules/observe/proc-enabling-telemetry-using-helm.adoc renamed to modules/analytics/proc-enabling-telemetry-using-helm.adoc

@@ -0,0 +1,61 @@
+[id="proc-disabling-telemetry-using-helm_{context}"]
+= Disabling telemetry data collection using the Helm Chart
+
+You can disable the telemetry data collection feature by using the Helm Chart.
+
+.Prerequisites
+
+* You have logged in as an administrator in the {ocp-short} web console.
+* You have installed {product} on {ocp-short} using the Helm Chart.
+
+.Procedure
+
+. In the *Developer* perspective of the {ocp-short} web console, go to the *Helm* view to see the list of Helm releases.
+. Click the *overflow* menu on the Helm release that you want to use and select *Upgrade*.
++
+[NOTE]
+====
+You can also create a new Helm release by clicking the *Create* button and edit the configuration to disable telemetry.
+====
+
+. Use either the *Form* view or *YAML* view to edit the Helm configuration:
+** Using *Form view*
++
+.. Expand *Root Schema → global → Dynamic plugins configuration. → List of dynamic plugins that should be installed in the backstage application*.
+.. Click the *Add list of dynamic plugins that should be installed in the backstage application.* link.
+
+.. Perform one of the following steps:
++
+*** If you have not configured the plugin, add the following value in the *Package specification of the dynamic plugin to install. It should be usable by the npm pack command.* field:
++
+`./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment`
++
+image::rhdh/disabling-telemetry.png[]
++
+*** If you have configured the plugin, find the *Package specification of the dynamic plugin to install. It should be usable by the npm pack command.* field with the `./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment` value.
+
+.. Select the *Disable the plugin* checkbox.
+.. Click *Upgrade*.
+
+** Using *YAML view*
++
+.. Perform one of the following steps:
++
+*** If you have not configured the plugin, add the following YAML code in your `values.yaml` Helm configuration file:
++
+[source,yaml]
+----
+# ...
+global:
+  dynamic:
+    plugins:
+      - package: './dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment'
+        disabled: true
+# ...
+----
++
+*** If you have configured the plugin, search it in your Helm configuration and set the value of the `plugins.disabled` parameter to `true`.
+
+.. Click *Upgrade*.
+
+

modules/observe/proc-enabling-telemetry-using-operator.adoc renamed to modules/analytics/proc-enabling-telemetry-using-operator.adoc

@@ -0,0 +1,49 @@
+[id="proc-disabling-telemetry-using-operator_{context}"]
+= Disabling telemetry data collection using the Operator
+
+You can disable the telemetry data collection feature by using the Operator.
+
+.Prerequisites
+
+* You have logged in as an administrator in the {ocp-short} web console.
+* You have installed {product} on {ocp-short} using the Operator.
+
+.Procedure
+
+. Perform one of the following steps:
++
+* If you have created the `dynamic-plugins-rhdh` ConfigMap file and not configured the `analytics-provider-segment` plugin, add the plugin to the list of plugins and set its `plugins.disabled` parameter to `true`.
++
+* If you have created the `dynamic-plugins-rhdh` ConfigMap file and configured the `analytics-provider-segment` plugin, search the plugin in 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/backstage-community-plugin-analytics-provider-segment'
+        disabled: true
+----
+
+. Set the value of the `dynamicPluginsConfigMapName` parameter to the name of your `dynamic-plugins-rhdh` config map in your `{product-custom-resource-type}` custom resource:
++
+[source,yaml]
+----
+# ...
+spec:
+  application:
+    dynamicPluginsConfigMapName: dynamic-plugins-rhdh
+# ...
+----
+
+. Save the configuration changes.
+
+

modules/observe/ref-customizing-telemetry-segment.adoc renamed to modules/analytics/ref-customizing-telemetry-segment.adoc

@@ -0,0 +1,58 @@
+[id="proc-enabling-telemetry-using-helm_{context}"]
+= Enabling telemetry data collection using the Helm Chart
+
+You can enable the telemetry data collection feature by using the Helm Chart.
+
+.Prerequisites
+
+* You have logged in as an administrator in the {ocp-short} web console.
+* You have installed {product} on {ocp-short} using the Helm Chart.
+
+.Procedure
+
+. In the *Developer* perspective of the {ocp-short} web console, go to the *Helm* view to see the list of Helm releases.
+. Click the *overflow* menu on the Helm release that you want to use and select *Upgrade*.
++
+[NOTE]
+====
+You can also create a new Helm release by clicking the *Create* button and edit the configuration to enable telemetry.
+====
+
+. Use either the *Form* view or *YAML* view to edit the Helm configuration:
+** Using *Form view*
++
+.. Expand *Root Schema → global → Dynamic plugins configuration. → List of dynamic plugins that should be installed in the backstage application*.
+.. Click the *Add list of dynamic plugins that should be installed in the backstage application.* link.
+
+.. Perform one of the following steps:
++
+*** If you have not configured the plugin, add the following value in the *Package specification of the dynamic plugin to install. It should be usable by the npm pack command.* field:
++
+`./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment`
++
+*** If you have configured the plugin, find the *Package specification of the dynamic plugin to install. It should be usable by the npm pack command.* field with the `./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment` value.
+
+.. Clear the *Disable the plugin* checkbox.
+.. Click *Upgrade*.
+
+** Using *YAML view*
++
+.. Perform one of the following steps:
++
+*** If you have not configured the plugin, add the following YAML code in your Helm configuration file:
++
+[source,yaml]
+----
+# ...
+global:
+  dynamic:
+    plugins:
+      - package: './dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment'
+        disabled: false
+# ...
+----
++
+*** If you have configured the plugin, search it in your Helm configuration and set the value of the `plugins.disabled` parameter to `false`.
+
+.. Click *Upgrade*.
+