From 7678e0b53ac25bee53838c81434ebf592a3cf995 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 24 Apr 2025 15:18:23 +0200 Subject: [PATCH 1/7] 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 --- assemblies/assembly-rhdh-telemetry.adoc | 36 +++++++---- ...tomizing-telemetry-segment-using-helm.adoc | 2 +- ...zing-telemetry-segment-using-operator.adoc | 2 +- .../proc-disabling-telemetry-using-helm.adoc | 0 ...oc-disabling-telemetry-using-operator.adoc | 0 .../proc-enabling-telemetry-using-helm.adoc | 0 ...roc-enabling-telemetry-using-operator.adoc | 0 .../ref-customizing-telemetry-segment.adoc | 0 .../ref-disabling-telemetry.adoc | 0 .../ref-enabling-telemetry.adoc | 0 ...tomizing-telemetry-segment-using-helm.adoc | 42 +++++++++++++ ...zing-telemetry-segment-using-operator.adoc | 28 +++++++++ .../proc-disabling-telemetry-using-helm.adoc | 61 +++++++++++++++++++ ...oc-disabling-telemetry-using-operator.adoc | 49 +++++++++++++++ .../proc-enabling-telemetry-using-helm.adoc | 58 ++++++++++++++++++ ...roc-enabling-telemetry-using-operator.adoc | 48 +++++++++++++++ .../ref-customizing-telemetry-segment.adoc | 12 ++++ .../analytics/ref-disabling-telemetry.adoc | 6 ++ .../analytics/ref-enabling-telemetry.adoc | 5 ++ titles/telemetry/master.adoc | 8 +-- 20 files changed, 339 insertions(+), 18 deletions(-) rename modules/{observe => analytics}/proc-customizing-telemetry-segment-using-helm.adoc (95%) rename modules/{observe => analytics}/proc-customizing-telemetry-segment-using-operator.adoc (92%) rename modules/{observe => analytics}/proc-disabling-telemetry-using-helm.adoc (100%) rename modules/{observe => analytics}/proc-disabling-telemetry-using-operator.adoc (100%) rename modules/{observe => analytics}/proc-enabling-telemetry-using-helm.adoc (100%) rename modules/{observe => analytics}/proc-enabling-telemetry-using-operator.adoc (100%) rename modules/{observe => analytics}/ref-customizing-telemetry-segment.adoc (100%) rename modules/{observe => analytics}/ref-disabling-telemetry.adoc (100%) rename modules/{observe => analytics}/ref-enabling-telemetry.adoc (100%) create mode 100644 modules/observe/analytics/proc-customizing-telemetry-segment-using-helm.adoc create mode 100644 modules/observe/analytics/proc-customizing-telemetry-segment-using-operator.adoc create mode 100644 modules/observe/analytics/proc-disabling-telemetry-using-helm.adoc create mode 100644 modules/observe/analytics/proc-disabling-telemetry-using-operator.adoc create mode 100644 modules/observe/analytics/proc-enabling-telemetry-using-helm.adoc create mode 100644 modules/observe/analytics/proc-enabling-telemetry-using-operator.adoc create mode 100644 modules/observe/analytics/ref-customizing-telemetry-segment.adoc create mode 100644 modules/observe/analytics/ref-disabling-telemetry.adoc create mode 100644 modules/observe/analytics/ref-enabling-telemetry.adoc diff --git a/assemblies/assembly-rhdh-telemetry.adoc b/assemblies/assembly-rhdh-telemetry.adoc index 00ee46fdda..6dc4c673d9 100644 --- a/assemblies/assembly-rhdh-telemetry.adoc +++ b/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] diff --git a/modules/observe/proc-customizing-telemetry-segment-using-helm.adoc b/modules/analytics/proc-customizing-telemetry-segment-using-helm.adoc similarity index 95% rename from modules/observe/proc-customizing-telemetry-segment-using-helm.adoc rename to modules/analytics/proc-customizing-telemetry-segment-using-helm.adoc index 3b61cbb981..0be73355c7 100644 --- a/modules/observe/proc-customizing-telemetry-segment-using-helm.adoc +++ b/modules/analytics/proc-customizing-telemetry-segment-using-helm.adoc @@ -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. diff --git a/modules/observe/proc-customizing-telemetry-segment-using-operator.adoc b/modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc similarity index 92% rename from modules/observe/proc-customizing-telemetry-segment-using-operator.adoc rename to modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc index 0d08938f23..f0357e9e38 100644 --- a/modules/observe/proc-customizing-telemetry-segment-using-operator.adoc +++ b/modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc @@ -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. diff --git a/modules/observe/proc-disabling-telemetry-using-helm.adoc b/modules/analytics/proc-disabling-telemetry-using-helm.adoc similarity index 100% rename from modules/observe/proc-disabling-telemetry-using-helm.adoc rename to modules/analytics/proc-disabling-telemetry-using-helm.adoc diff --git a/modules/observe/proc-disabling-telemetry-using-operator.adoc b/modules/analytics/proc-disabling-telemetry-using-operator.adoc similarity index 100% rename from modules/observe/proc-disabling-telemetry-using-operator.adoc rename to modules/analytics/proc-disabling-telemetry-using-operator.adoc diff --git a/modules/observe/proc-enabling-telemetry-using-helm.adoc b/modules/analytics/proc-enabling-telemetry-using-helm.adoc similarity index 100% rename from modules/observe/proc-enabling-telemetry-using-helm.adoc rename to modules/analytics/proc-enabling-telemetry-using-helm.adoc diff --git a/modules/observe/proc-enabling-telemetry-using-operator.adoc b/modules/analytics/proc-enabling-telemetry-using-operator.adoc similarity index 100% rename from modules/observe/proc-enabling-telemetry-using-operator.adoc rename to modules/analytics/proc-enabling-telemetry-using-operator.adoc diff --git a/modules/observe/ref-customizing-telemetry-segment.adoc b/modules/analytics/ref-customizing-telemetry-segment.adoc similarity index 100% rename from modules/observe/ref-customizing-telemetry-segment.adoc rename to modules/analytics/ref-customizing-telemetry-segment.adoc diff --git a/modules/observe/ref-disabling-telemetry.adoc b/modules/analytics/ref-disabling-telemetry.adoc similarity index 100% rename from modules/observe/ref-disabling-telemetry.adoc rename to modules/analytics/ref-disabling-telemetry.adoc diff --git a/modules/observe/ref-enabling-telemetry.adoc b/modules/analytics/ref-enabling-telemetry.adoc similarity index 100% rename from modules/observe/ref-enabling-telemetry.adoc rename to modules/analytics/ref-enabling-telemetry.adoc diff --git a/modules/observe/analytics/proc-customizing-telemetry-segment-using-helm.adoc b/modules/observe/analytics/proc-customizing-telemetry-segment-using-helm.adoc new file mode 100644 index 0000000000..0be73355c7 --- /dev/null +++ b/modules/observe/analytics/proc-customizing-telemetry-segment-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: # <1> +# ... +---- +<1> Replace `` with a unique identifier for your Segment source. + +.. Click *Upgrade*. diff --git a/modules/observe/analytics/proc-customizing-telemetry-segment-using-operator.adoc b/modules/observe/analytics/proc-customizing-telemetry-segment-using-operator.adoc new file mode 100644 index 0000000000..f0357e9e38 --- /dev/null +++ b/modules/observe/analytics/proc-customizing-telemetry-segment-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: # <1> +# ... +---- +<1> Replace `` with a unique identifier for your Segment source. + +. Save the configuration changes. diff --git a/modules/observe/analytics/proc-disabling-telemetry-using-helm.adoc b/modules/observe/analytics/proc-disabling-telemetry-using-helm.adoc new file mode 100644 index 0000000000..4fbcde0b7e --- /dev/null +++ b/modules/observe/analytics/proc-disabling-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*. + + diff --git a/modules/observe/analytics/proc-disabling-telemetry-using-operator.adoc b/modules/observe/analytics/proc-disabling-telemetry-using-operator.adoc new file mode 100644 index 0000000000..9622935d40 --- /dev/null +++ b/modules/observe/analytics/proc-disabling-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. + + diff --git a/modules/observe/analytics/proc-enabling-telemetry-using-helm.adoc b/modules/observe/analytics/proc-enabling-telemetry-using-helm.adoc new file mode 100644 index 0000000000..c73230fc53 --- /dev/null +++ b/modules/observe/analytics/proc-enabling-telemetry-using-helm.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*. + diff --git a/modules/observe/analytics/proc-enabling-telemetry-using-operator.adoc b/modules/observe/analytics/proc-enabling-telemetry-using-operator.adoc new file mode 100644 index 0000000000..beddcdf01e --- /dev/null +++ b/modules/observe/analytics/proc-enabling-telemetry-using-operator.adoc @@ -0,0 +1,48 @@ +[id="proc-enabling-telemetry-using-operator_{context}"] += Enabling telemetry data collection using the Operator + +You can enable 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 `false`. ++ +* 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 `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/backstage-community-plugin-analytics-provider-segment' + disabled: false +---- + +. 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. + diff --git a/modules/observe/analytics/ref-customizing-telemetry-segment.adoc b/modules/observe/analytics/ref-customizing-telemetry-segment.adoc new file mode 100644 index 0000000000..fc9b0fd2ee --- /dev/null +++ b/modules/observe/analytics/ref-customizing-telemetry-segment.adoc @@ -0,0 +1,12 @@ +[id="customizing-telemetry-segment_{context}"] += Customizing Segment source + + +The `analytics-provider-segment` plugin sends the collected web analytics data to {company-name} by default. However, you can configure a new Segment source that receives web analytics 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 link:{telemetry-data-collection-book-url}[{telemetry-data-collection-book-title}]. You might also require to create your own web analytics data collection notice for your application users. +==== + + diff --git a/modules/observe/analytics/ref-disabling-telemetry.adoc b/modules/observe/analytics/ref-disabling-telemetry.adoc new file mode 100644 index 0000000000..66bf4470e1 --- /dev/null +++ b/modules/observe/analytics/ref-disabling-telemetry.adoc @@ -0,0 +1,6 @@ +[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. + + diff --git a/modules/observe/analytics/ref-enabling-telemetry.adoc b/modules/observe/analytics/ref-enabling-telemetry.adoc new file mode 100644 index 0000000000..9df4622324 --- /dev/null +++ b/modules/observe/analytics/ref-enabling-telemetry.adoc @@ -0,0 +1,5 @@ +[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. + diff --git a/titles/telemetry/master.adoc b/titles/telemetry/master.adoc index 52a59af949..715b79c8ed 100644 --- a/titles/telemetry/master.adoc +++ b/titles/telemetry/master.adoc @@ -1,11 +1,11 @@ include::artifacts/attributes.adoc[] :context: title-telemetry :imagesdir: images -:title: Telemetry data collection -:subtitle: Collecting and analyzing telemetry data to enhance {product} experience -:abstract: As a {product} administrator, you can collect and analyze telemetry data to enhance your {product} experience. +:title: Telemetry data collection and analysis +:subtitle: Collecting and analyzing web analytics and system observability data to enhance {product} experience +:abstract: As a {product} administrator, you can collect and analyze two distinct types of telemetry data: web analytics using Segment and system observability using OpenTelemetry, to enhance the {product} experience. = {title} -//Telemetry data collection +//Telemetry data collection and analysis include::assemblies/assembly-rhdh-telemetry.adoc[leveloffset=+1] From d7874e7789d8d70ceea93ec1ff8dc09366953a1a Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Thu, 24 Apr 2025 16:26:35 +0200 Subject: [PATCH 2/7] Reorganize Segment/Telemetry instructions into its own category --- ...tomizing-telemetry-segment-using-helm.adoc | 42 ------------- ...zing-telemetry-segment-using-operator.adoc | 28 --------- .../proc-disabling-telemetry-using-helm.adoc | 61 ------------------- ...oc-disabling-telemetry-using-operator.adoc | 49 --------------- .../proc-enabling-telemetry-using-helm.adoc | 58 ------------------ ...roc-enabling-telemetry-using-operator.adoc | 48 --------------- .../ref-customizing-telemetry-segment.adoc | 12 ---- .../analytics/ref-disabling-telemetry.adoc | 6 -- modules/analytics/ref-enabling-telemetry.adoc | 5 -- 9 files changed, 309 deletions(-) delete mode 100644 modules/analytics/proc-customizing-telemetry-segment-using-helm.adoc delete mode 100644 modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc delete mode 100644 modules/analytics/proc-disabling-telemetry-using-helm.adoc delete mode 100644 modules/analytics/proc-disabling-telemetry-using-operator.adoc delete mode 100644 modules/analytics/proc-enabling-telemetry-using-helm.adoc delete mode 100644 modules/analytics/proc-enabling-telemetry-using-operator.adoc delete mode 100644 modules/analytics/ref-customizing-telemetry-segment.adoc delete mode 100644 modules/analytics/ref-disabling-telemetry.adoc delete mode 100644 modules/analytics/ref-enabling-telemetry.adoc diff --git a/modules/analytics/proc-customizing-telemetry-segment-using-helm.adoc b/modules/analytics/proc-customizing-telemetry-segment-using-helm.adoc deleted file mode 100644 index 0be73355c7..0000000000 --- a/modules/analytics/proc-customizing-telemetry-segment-using-helm.adoc +++ /dev/null @@ -1,42 +0,0 @@ -[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: # <1> -# ... ----- -<1> Replace `` with a unique identifier for your Segment source. - -.. Click *Upgrade*. diff --git a/modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc b/modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc deleted file mode 100644 index f0357e9e38..0000000000 --- a/modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc +++ /dev/null @@ -1,28 +0,0 @@ -[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: # <1> -# ... ----- -<1> Replace `` with a unique identifier for your Segment source. - -. Save the configuration changes. diff --git a/modules/analytics/proc-disabling-telemetry-using-helm.adoc b/modules/analytics/proc-disabling-telemetry-using-helm.adoc deleted file mode 100644 index 4fbcde0b7e..0000000000 --- a/modules/analytics/proc-disabling-telemetry-using-helm.adoc +++ /dev/null @@ -1,61 +0,0 @@ -[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*. - - diff --git a/modules/analytics/proc-disabling-telemetry-using-operator.adoc b/modules/analytics/proc-disabling-telemetry-using-operator.adoc deleted file mode 100644 index 9622935d40..0000000000 --- a/modules/analytics/proc-disabling-telemetry-using-operator.adoc +++ /dev/null @@ -1,49 +0,0 @@ -[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. - - diff --git a/modules/analytics/proc-enabling-telemetry-using-helm.adoc b/modules/analytics/proc-enabling-telemetry-using-helm.adoc deleted file mode 100644 index c73230fc53..0000000000 --- a/modules/analytics/proc-enabling-telemetry-using-helm.adoc +++ /dev/null @@ -1,58 +0,0 @@ -[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*. - diff --git a/modules/analytics/proc-enabling-telemetry-using-operator.adoc b/modules/analytics/proc-enabling-telemetry-using-operator.adoc deleted file mode 100644 index beddcdf01e..0000000000 --- a/modules/analytics/proc-enabling-telemetry-using-operator.adoc +++ /dev/null @@ -1,48 +0,0 @@ -[id="proc-enabling-telemetry-using-operator_{context}"] -= Enabling telemetry data collection using the Operator - -You can enable 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 `false`. -+ -* 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 `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/backstage-community-plugin-analytics-provider-segment' - disabled: false ----- - -. 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. - diff --git a/modules/analytics/ref-customizing-telemetry-segment.adoc b/modules/analytics/ref-customizing-telemetry-segment.adoc deleted file mode 100644 index 9ee7698713..0000000000 --- a/modules/analytics/ref-customizing-telemetry-segment.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[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 link:{telemetry-data-collection-book-url}[{telemetry-data-collection-book-title}]. You might also require to create your own telemetry data collection notice for your application users. -==== - - diff --git a/modules/analytics/ref-disabling-telemetry.adoc b/modules/analytics/ref-disabling-telemetry.adoc deleted file mode 100644 index 66bf4470e1..0000000000 --- a/modules/analytics/ref-disabling-telemetry.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[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. - - diff --git a/modules/analytics/ref-enabling-telemetry.adoc b/modules/analytics/ref-enabling-telemetry.adoc deleted file mode 100644 index 9df4622324..0000000000 --- a/modules/analytics/ref-enabling-telemetry.adoc +++ /dev/null @@ -1,5 +0,0 @@ -[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. - From 96f5892a71f64b91937a3f47410b83fdddc22e9a Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 30 Apr 2025 13:18:24 +0200 Subject: [PATCH 3/7] Reorganize Segment/Telemetry instructions into its own category --- assemblies/assembly-rhdh-telemetry.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assemblies/assembly-rhdh-telemetry.adoc b/assemblies/assembly-rhdh-telemetry.adoc index 6dc4c673d9..066b6b4a2c 100644 --- a/assemblies/assembly-rhdh-telemetry.adoc +++ b/assemblies/assembly-rhdh-telemetry.adoc @@ -22,7 +22,7 @@ Web Analytics tracks user behavior and interactions with {product}. Specifically *System Observability (OpenTelemetry)* -System Observability tracks the performance of the {product-very-short}. Specifically, it tracks the following: +System Observability tracks the performance of the {product-very-short}. Specifically, it tracks the following metrics: * 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). From cf12513bafb3d9174e3d9c2c4115583fad9ba529 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Wed, 30 Apr 2025 16:15:38 +0200 Subject: [PATCH 4/7] Reorganize Segment/Telemetry instructions into its own category --- assemblies/assembly-rhdh-telemetry.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/assemblies/assembly-rhdh-telemetry.adoc b/assemblies/assembly-rhdh-telemetry.adoc index 066b6b4a2c..6f1ce2d50b 100644 --- a/assemblies/assembly-rhdh-telemetry.adoc +++ b/assemblies/assembly-rhdh-telemetry.adoc @@ -15,7 +15,7 @@ As an administrator, you can disable the telemetry data collection feature based 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, time zone, user agent including browser and OS details. +* System-related information, for example, locale, time zone, user agent including browser and operating system 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. @@ -25,7 +25,7 @@ Web Analytics tracks user behavior and interactions with {product}. Specifically System Observability tracks the performance of the {product-very-short}. Specifically, it tracks the following metrics: * 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). +* Information about system components, such as the locale, time zone, 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. From 02ac3ccb5320a37b258c3fc525b07068e5a386d3 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 2 May 2025 15:35:35 +0200 Subject: [PATCH 5/7] Reorganize Segment/Telemetry instructions into its own category --- .../assembly-customizing-segment-source.adoc | 17 ++++++ ...y-disabling-telemetry-data-collection.adoc | 11 ++++ ...ly-enabling-telemetry-data-collection.adoc | 6 ++- assemblies/assembly-rhdh-telemetry.adoc | 53 ------------------- ...elemetry-data-collection-and-analysis.adoc | 34 ++++++++++++ ...ustomizing-segment-source-using-helm.adoc} | 4 +- ...zing-telemetry-segment-using-operator.adoc | 2 +- .../proc-disabling-telemetry-using-helm.adoc | 0 ...oc-disabling-telemetry-using-operator.adoc | 0 .../proc-enabling-telemetry-using-helm.adoc | 0 ...roc-enabling-telemetry-using-operator.adoc | 0 .../ref-customizing-telemetry-segment.adoc | 12 ----- .../analytics/ref-disabling-telemetry.adoc | 6 --- titles/telemetry/master.adoc | 11 +++- 14 files changed, 80 insertions(+), 76 deletions(-) create mode 100644 assemblies/assembly-customizing-segment-source.adoc create mode 100644 assemblies/assembly-disabling-telemetry-data-collection.adoc rename modules/observe/analytics/ref-enabling-telemetry.adoc => assemblies/assembly-enabling-telemetry-data-collection.adoc (55%) delete mode 100644 assemblies/assembly-rhdh-telemetry.adoc create mode 100644 modules/analytics/con-telemetry-data-collection-and-analysis.adoc rename modules/{observe/analytics/proc-customizing-telemetry-segment-using-helm.adoc => analytics/proc-customizing-segment-source-using-helm.adoc} (93%) rename modules/{observe => }/analytics/proc-customizing-telemetry-segment-using-operator.adoc (96%) rename modules/{observe => }/analytics/proc-disabling-telemetry-using-helm.adoc (100%) rename modules/{observe => }/analytics/proc-disabling-telemetry-using-operator.adoc (100%) rename modules/{observe => }/analytics/proc-enabling-telemetry-using-helm.adoc (100%) rename modules/{observe => }/analytics/proc-enabling-telemetry-using-operator.adoc (100%) delete mode 100644 modules/observe/analytics/ref-customizing-telemetry-segment.adoc delete mode 100644 modules/observe/analytics/ref-disabling-telemetry.adoc diff --git a/assemblies/assembly-customizing-segment-source.adoc b/assemblies/assembly-customizing-segment-source.adoc new file mode 100644 index 0000000000..65ea9cb54d --- /dev/null +++ b/assemblies/assembly-customizing-segment-source.adoc @@ -0,0 +1,17 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-customizing-segment-source"] += Customizing Segment source + +The `analytics-provider-segment` plugin sends the collected web analytics data to {company-name} by default. However, you can configure a new Segment source that receives web analytics data based on your needs. For configuration, you need a unique Segment write key that points to the Segment source. + +[NOTE] +==== +Create your own web analytics data collection notice for your application users. +==== + +include::modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc[leveloffset=+1] + +include::modules/analytics/proc-customizing-segment-source-using-helm.adoc[leveloffset=+1] + +.Additional resources +* To learn how to collect and analyze the same set of data, see link:{telemetry-data-collection-book-url}[{telemetry-data-collection-book-title}]. \ No newline at end of file diff --git a/assemblies/assembly-disabling-telemetry-data-collection.adoc b/assemblies/assembly-disabling-telemetry-data-collection.adoc new file mode 100644 index 0000000000..702c8b7969 --- /dev/null +++ b/assemblies/assembly-disabling-telemetry-data-collection.adoc @@ -0,0 +1,11 @@ +:_mod-docs-content-type: ASSEMBLY +[id="assembly-disabling-telemetry-data-collection"] += 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. + +As an administrator, 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:{telemetry-data-collection-book-url}#proc-disabling-telemetry-using-operator_title-telemetry[Disabling telemetry data collection in {product-very-short}] section. + +include::modules/analytics/proc-disabling-telemetry-using-operator.adoc[leveloffset=+1] + +include::modules/analytics/proc-disabling-telemetry-using-helm.adoc[leveloffset=+1] \ No newline at end of file diff --git a/modules/observe/analytics/ref-enabling-telemetry.adoc b/assemblies/assembly-enabling-telemetry-data-collection.adoc similarity index 55% rename from modules/observe/analytics/ref-enabling-telemetry.adoc rename to assemblies/assembly-enabling-telemetry-data-collection.adoc index 9df4622324..8e12009eb6 100644 --- a/modules/observe/analytics/ref-enabling-telemetry.adoc +++ b/assemblies/assembly-enabling-telemetry-data-collection.adoc @@ -1,5 +1,9 @@ -[id="enabling-telemetry-data-collection_{context}"] +:_mod-docs-content-type: ASSEMBLY +[id="assembly-enabling-telemetry-data-collection"] = 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. +include::modules/analytics/proc-enabling-telemetry-using-operator.adoc[leveloffset=+1] + +include::modules/analytics/proc-enabling-telemetry-using-helm.adoc[leveloffset=+1] \ No newline at end of file diff --git a/assemblies/assembly-rhdh-telemetry.adoc b/assemblies/assembly-rhdh-telemetry.adoc deleted file mode 100644 index 6f1ce2d50b..0000000000 --- a/assemblies/assembly-rhdh-telemetry.adoc +++ /dev/null @@ -1,53 +0,0 @@ -[id="assembly-rhdh-telemetry"] -= 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. - -[IMPORTANT] -==== -As an administrator, 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:{telemetry-data-collection-book-url}#proc-disabling-telemetry-using-operator_title-telemetry[Disabling telemetry data collection in {product-very-short}] section. -==== - -{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, time zone, user agent including browser and operating system 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. - -*System Observability (OpenTelemetry)* - -System Observability tracks the performance of the {product-very-short}. Specifically, it tracks the following metrics: - -* Key system metrics such as CPU usage, memory usage, and other performance indicators. -* Information about system components, such as the locale, time zone, 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/analytics/ref-disabling-telemetry.adoc[leveloffset=+1] - -include::modules/observe/analytics/proc-disabling-telemetry-using-operator.adoc[leveloffset=+2] - -include::modules/observe/analytics/proc-disabling-telemetry-using-helm.adoc[leveloffset=+2] - -// enabling telemetry -include::modules/observe/analytics/ref-enabling-telemetry.adoc[leveloffset=+1] - -include::modules/observe/analytics/proc-enabling-telemetry-using-operator.adoc[leveloffset=+2] - -include::modules/observe/analytics/proc-enabling-telemetry-using-helm.adoc[leveloffset=+2] - -// customizing telemetry segment source -include::modules/observe/analytics/ref-customizing-telemetry-segment.adoc[leveloffset=+1] - -include::modules/observe/analytics/proc-customizing-telemetry-segment-using-operator.adoc[leveloffset=+2] - -include::modules/observe/analytics/proc-customizing-telemetry-segment-using-helm.adoc[leveloffset=+2] diff --git a/modules/analytics/con-telemetry-data-collection-and-analysis.adoc b/modules/analytics/con-telemetry-data-collection-and-analysis.adoc new file mode 100644 index 0000000000..a746709881 --- /dev/null +++ b/modules/analytics/con-telemetry-data-collection-and-analysis.adoc @@ -0,0 +1,34 @@ +[id="con-telemetry-data-collection-and-analysis_{context}"] += 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. + +{company-name} collects and analyzes the following data: + +Web Analytics:: + +* Web Analytics use the Segment tool. + +* It is the tracking of 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, time zone, user agent including browser and operating system 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. + +System Observability:: + +* System Observability uses the OpenTelemetry tool. + +* It is the tracking of the performance of the {product-very-short}. + +Specifically, it tracks the following metrics: + +* Key system metrics such as CPU usage, memory usage, and other performance indicators. +* Information about system components, such as the locale, time zone, 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. \ No newline at end of file diff --git a/modules/observe/analytics/proc-customizing-telemetry-segment-using-helm.adoc b/modules/analytics/proc-customizing-segment-source-using-helm.adoc similarity index 93% rename from modules/observe/analytics/proc-customizing-telemetry-segment-using-helm.adoc rename to modules/analytics/proc-customizing-segment-source-using-helm.adoc index 0be73355c7..7723026ea6 100644 --- a/modules/observe/analytics/proc-customizing-telemetry-segment-using-helm.adoc +++ b/modules/analytics/proc-customizing-segment-source-using-helm.adoc @@ -1,7 +1,7 @@ -[id="proc-customizing-telemetry-segment-using-helm_{context}"] +[id="proc-customizing-segment-source-using-helm_{context}"] = Customizing Segment source using the Helm Chart -You can configure integration with your Segment source by using the Helm Chart. +You can configure integration with your Segment source by using the {product} Helm Chart. .Prerequisites diff --git a/modules/observe/analytics/proc-customizing-telemetry-segment-using-operator.adoc b/modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc similarity index 96% rename from modules/observe/analytics/proc-customizing-telemetry-segment-using-operator.adoc rename to modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc index f0357e9e38..5a1f01c9b2 100644 --- a/modules/observe/analytics/proc-customizing-telemetry-segment-using-operator.adoc +++ b/modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc @@ -1,7 +1,7 @@ [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. +You can configure integration with your Segment source by using the {product} Operator. .Prerequisites diff --git a/modules/observe/analytics/proc-disabling-telemetry-using-helm.adoc b/modules/analytics/proc-disabling-telemetry-using-helm.adoc similarity index 100% rename from modules/observe/analytics/proc-disabling-telemetry-using-helm.adoc rename to modules/analytics/proc-disabling-telemetry-using-helm.adoc diff --git a/modules/observe/analytics/proc-disabling-telemetry-using-operator.adoc b/modules/analytics/proc-disabling-telemetry-using-operator.adoc similarity index 100% rename from modules/observe/analytics/proc-disabling-telemetry-using-operator.adoc rename to modules/analytics/proc-disabling-telemetry-using-operator.adoc diff --git a/modules/observe/analytics/proc-enabling-telemetry-using-helm.adoc b/modules/analytics/proc-enabling-telemetry-using-helm.adoc similarity index 100% rename from modules/observe/analytics/proc-enabling-telemetry-using-helm.adoc rename to modules/analytics/proc-enabling-telemetry-using-helm.adoc diff --git a/modules/observe/analytics/proc-enabling-telemetry-using-operator.adoc b/modules/analytics/proc-enabling-telemetry-using-operator.adoc similarity index 100% rename from modules/observe/analytics/proc-enabling-telemetry-using-operator.adoc rename to modules/analytics/proc-enabling-telemetry-using-operator.adoc diff --git a/modules/observe/analytics/ref-customizing-telemetry-segment.adoc b/modules/observe/analytics/ref-customizing-telemetry-segment.adoc deleted file mode 100644 index fc9b0fd2ee..0000000000 --- a/modules/observe/analytics/ref-customizing-telemetry-segment.adoc +++ /dev/null @@ -1,12 +0,0 @@ -[id="customizing-telemetry-segment_{context}"] -= Customizing Segment source - - -The `analytics-provider-segment` plugin sends the collected web analytics data to {company-name} by default. However, you can configure a new Segment source that receives web analytics 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 link:{telemetry-data-collection-book-url}[{telemetry-data-collection-book-title}]. You might also require to create your own web analytics data collection notice for your application users. -==== - - diff --git a/modules/observe/analytics/ref-disabling-telemetry.adoc b/modules/observe/analytics/ref-disabling-telemetry.adoc deleted file mode 100644 index 66bf4470e1..0000000000 --- a/modules/observe/analytics/ref-disabling-telemetry.adoc +++ /dev/null @@ -1,6 +0,0 @@ -[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. - - diff --git a/titles/telemetry/master.adoc b/titles/telemetry/master.adoc index 715b79c8ed..2608f4895a 100644 --- a/titles/telemetry/master.adoc +++ b/titles/telemetry/master.adoc @@ -8,4 +8,13 @@ include::artifacts/attributes.adoc[] = {title} //Telemetry data collection and analysis -include::assemblies/assembly-rhdh-telemetry.adoc[leveloffset=+1] +include::modules/analytics/con-telemetry-data-collection-and-analysis.adoc[leveloffset=+1] + +// disabling telemetry +include::assemblies/assembly-disabling-telemetry-data-collection.adoc[leveloffset=+1] + +// enabling telemetry +include::assemblies/assembly-enabling-telemetry-data-collection.adoc[leveloffset=+1] + +// customizing segment source +include::assemblies/assembly-customizing-segment-source.adoc[leveloffset=+1] \ No newline at end of file From f1167cef003a98d288c78abcb5245589b7964aff Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Fri, 2 May 2025 15:39:12 +0200 Subject: [PATCH 6/7] Reorganize Segment/Telemetry instructions into its own category --- .../analytics/con-telemetry-data-collection-and-analysis.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/analytics/con-telemetry-data-collection-and-analysis.adoc b/modules/analytics/con-telemetry-data-collection-and-analysis.adoc index a746709881..5019300243 100644 --- a/modules/analytics/con-telemetry-data-collection-and-analysis.adoc +++ b/modules/analytics/con-telemetry-data-collection-and-analysis.adoc @@ -9,7 +9,7 @@ Web Analytics:: * Web Analytics use the Segment tool. -* It is the tracking of user behavior and interactions with {product} +* It is the tracking of user behavior and interactions with {product}. Specifically, it tracks the following: From 70d65c239e909f0dd0ac30d4fc911344334256e1 Mon Sep 17 00:00:00 2001 From: GitHub Actions Date: Mon, 5 May 2025 12:14:46 +0200 Subject: [PATCH 7/7] Reorganize Segment/Telemetry instructions into its own category --- .../assembly-customizing-segment-source.adoc | 6 +++--- ...mbly-disabling-telemetry-data-collection.adoc | 2 +- ...embly-enabling-telemetry-data-collection.adoc | 2 +- ...n-telemetry-data-collection-and-analysis.adoc | 16 +++++----------- ...egment-source-using-helm-the-helm-chart.adoc} | 2 +- ...izing-segment-source-using-the-operator.adoc} | 0 6 files changed, 11 insertions(+), 17 deletions(-) rename modules/analytics/{proc-customizing-segment-source-using-helm.adoc => proc-customizing-segment-source-using-helm-the-helm-chart.adoc} (94%) rename modules/analytics/{proc-customizing-telemetry-segment-using-operator.adoc => proc-customizing-segment-source-using-the-operator.adoc} (100%) diff --git a/assemblies/assembly-customizing-segment-source.adoc b/assemblies/assembly-customizing-segment-source.adoc index 65ea9cb54d..010cb9bca9 100644 --- a/assemblies/assembly-customizing-segment-source.adoc +++ b/assemblies/assembly-customizing-segment-source.adoc @@ -1,5 +1,5 @@ :_mod-docs-content-type: ASSEMBLY -[id="assembly-customizing-segment-source"] +[id="customizing-segment-source_{context}"] = Customizing Segment source The `analytics-provider-segment` plugin sends the collected web analytics data to {company-name} by default. However, you can configure a new Segment source that receives web analytics data based on your needs. For configuration, you need a unique Segment write key that points to the Segment source. @@ -9,9 +9,9 @@ The `analytics-provider-segment` plugin sends the collected web analytics data t Create your own web analytics data collection notice for your application users. ==== -include::modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc[leveloffset=+1] +include::modules/analytics/proc-customizing-segment-source-using-the-operator.adoc[leveloffset=+1] -include::modules/analytics/proc-customizing-segment-source-using-helm.adoc[leveloffset=+1] +include::modules/analytics/proc-customizing-segment-source-using-helm-the-helm-chart.adoc[leveloffset=+1] .Additional resources * To learn how to collect and analyze the same set of data, see link:{telemetry-data-collection-book-url}[{telemetry-data-collection-book-title}]. \ No newline at end of file diff --git a/assemblies/assembly-disabling-telemetry-data-collection.adoc b/assemblies/assembly-disabling-telemetry-data-collection.adoc index 702c8b7969..421d49db5b 100644 --- a/assemblies/assembly-disabling-telemetry-data-collection.adoc +++ b/assemblies/assembly-disabling-telemetry-data-collection.adoc @@ -1,5 +1,5 @@ :_mod-docs-content-type: ASSEMBLY -[id="assembly-disabling-telemetry-data-collection"] +[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. diff --git a/assemblies/assembly-enabling-telemetry-data-collection.adoc b/assemblies/assembly-enabling-telemetry-data-collection.adoc index 8e12009eb6..62fa2dc9dd 100644 --- a/assemblies/assembly-enabling-telemetry-data-collection.adoc +++ b/assemblies/assembly-enabling-telemetry-data-collection.adoc @@ -1,5 +1,5 @@ :_mod-docs-content-type: ASSEMBLY -[id="assembly-enabling-telemetry-data-collection"] +[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. diff --git a/modules/analytics/con-telemetry-data-collection-and-analysis.adoc b/modules/analytics/con-telemetry-data-collection-and-analysis.adoc index 5019300243..c5a48f3954 100644 --- a/modules/analytics/con-telemetry-data-collection-and-analysis.adoc +++ b/modules/analytics/con-telemetry-data-collection-and-analysis.adoc @@ -1,4 +1,4 @@ -[id="con-telemetry-data-collection-and-analysis_{context}"] +[id="telemetry-data-collection-and-analysis_{context}"] = 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. @@ -6,11 +6,8 @@ The telemetry data collection feature helps in collecting and analyzing the tele {company-name} collects and analyzes the following data: Web Analytics:: - -* Web Analytics use the Segment tool. - -* It is the tracking of user behavior and interactions with {product}. - +Web Analytics use the Segment tool. +It is the tracking of user behavior and interactions with {product}. Specifically, it tracks the following: * Events of page visits and clicks on links or buttons. @@ -20,11 +17,8 @@ Specifically, it tracks the following: * Anonymized username hashes, which are unique identifiers used solely to identify the number of unique users of the {product-very-short} application. System Observability:: - -* System Observability uses the OpenTelemetry tool. - -* It is the tracking of the performance of the {product-very-short}. - +System Observability uses the OpenTelemetry tool. +It is the tracking of the performance of the {product-very-short}. Specifically, it tracks the following metrics: * Key system metrics such as CPU usage, memory usage, and other performance indicators. diff --git a/modules/analytics/proc-customizing-segment-source-using-helm.adoc b/modules/analytics/proc-customizing-segment-source-using-helm-the-helm-chart.adoc similarity index 94% rename from modules/analytics/proc-customizing-segment-source-using-helm.adoc rename to modules/analytics/proc-customizing-segment-source-using-helm-the-helm-chart.adoc index 7723026ea6..08deb63aa0 100644 --- a/modules/analytics/proc-customizing-segment-source-using-helm.adoc +++ b/modules/analytics/proc-customizing-segment-source-using-helm-the-helm-chart.adoc @@ -1,4 +1,4 @@ -[id="proc-customizing-segment-source-using-helm_{context}"] +[id="customizing-segment-source-using-helm-the-helm-chart_{context}"] = Customizing Segment source using the Helm Chart You can configure integration with your Segment source by using the {product} Helm Chart. diff --git a/modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc b/modules/analytics/proc-customizing-segment-source-using-the-operator.adoc similarity index 100% rename from modules/analytics/proc-customizing-telemetry-segment-using-operator.adoc rename to modules/analytics/proc-customizing-segment-source-using-the-operator.adoc