Skip to content

Commit

Permalink
Added detailed procedures
Browse files Browse the repository at this point in the history
  • Loading branch information
shipsing committed May 6, 2024
1 parent 400e282 commit cbd00b7
Show file tree
Hide file tree
Showing 11 changed files with 238 additions and 113 deletions.
19 changes: 11 additions & 8 deletions admin/assembly-rhdh-telemetry.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -2,26 +2,29 @@

= Telemetry data collection

You can enable the telemetry data collection feature through the [`janus-idp
-backstage-plugin-analytics-provider-segment`](https://github.com/janus-idp/backstage-plugins/tree/main/plugins/analytics-provider-segment) plugin by default. Based on the data collected, Red Hat analyzes your use of the {product-short} application. This analysis helps Red Hat to provide you support for upgrades, optimizing performance or configuration, minimizing service impacts, identifying and remediating threats, troubleshooting, improving the offerings and user experience, and responding to your issues.
You can use the telemetry data collection feature by configuring the `janus-idp
-backstage-plugin-analytics-provider-segment` plugin. Based on the data collected, Red Hat analyzes your usage of the {product-short} application. This analysis helps in providing you support for upgrades, optimizing performance or configuration, minimizing service impacts, identifying and remediating threats, troubleshooting, improving the offerings and your experience, and responding to your issues.

This feature collects the following data about your {product-very-short} usage:

* Events-related information, for example, number of page visits, number of clicks on any links or buttons.
* IP address-related information. The IP addresses are anonymized and recorded as `0.0.0.0`.
* Username-related information. The usernames are recorded as an anonymized hash ID.
* User-related information, for example, locale, timezone, userAgent including browser and OS details.
* User-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.

Red Hat analyzes the collected data to understand your interactions with the {product-very-short} application without disclosing your identity and compromising your privacy. Red Hat uses the collected data only for internal analysis and to improve your experience with {product}.

You can enable or disable {product-very-short} telemetry data collection based on your needs.
With {product-very-short}, you can customize the telemetry data collection feature and the telemetry destination configuration based on your needs.


include::proc-enabling-telemetry-using-helm-chart.adoc[leveloffset=+1]
include::proc-enabling-telemetry.adoc[leveloffset=+1]

include::proc-disabling-telemetry-using-helm-chart.adoc[leveloffset=+1]
include::proc-customizing-telemetry-destination.adoc[leveloffset=+1]

include::proc-disabling-telemetry-for-local-development.adoc[leveloffset=+1]
include::proc-disabling-telemetry.adoc[leveloffset=+1]

include::proc-disabling-telemetry-in-local-environment.adoc[leveloffset=+1]

include::proc-disabling-telemetry-in-CI-environment.adoc[leveloffset=+1]

include::proc-disabling-telemetry-in-CI-environments.adoc[leveloffset=+1]
50 changes: 50 additions & 0 deletions admin/proc-customizing-telemetry-destination.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
[id='customizing-telemetry-destination_{context}']
= Customizing telemetry destination


The `analytics-provider-segment` plugin sends the collected telemetry data to Red Hat by default. However, you can configure a new destination that receives telemetry data based on your needs. For configuration, you need a unique segment key that points to the destination.


.Prerequisites
* You have an administrator role in the {product-short}.
* You have installed the `janus-idp
-backstage-plugin-analytics-provider-segment` plugin in {product-short}. For more information, see link:{LinkAdminGuide}#rhdh-installing-dynamic-plugins[Dynamic plugin installation].

.Procedure

. Configure a new telemetry destination by using one of the following options:
+
.Using Helm Chart

* Add the following YAML code in your Helm configuration file:
+
[source,yaml]
----
gupstream:
backstage:
extraEnvVars:
- name: SEGMENT_WRITE_KEY
value: <segment_key>
----
+
where::
`<segment_key>` denotes a unique identifier for destination configuration.

+
.Using Operator

* Add the following YAML code in your {product-very-short} ConfigMap file:
+
[source,yaml]
----
extraEnvs:
envs:
- name: SEGMENT_WRITE_KEY
value: <segment_key>
----
+
where::
`<segment_key>` denotes a unique identifier for destination configuration.

. Save the configuration changes.

25 changes: 0 additions & 25 deletions admin/proc-disabling-telemetry-for-local-development.adoc

This file was deleted.

16 changes: 16 additions & 0 deletions admin/proc-disabling-telemetry-in-CI-environment.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
[id='disabling-telemetry-in-CI-environment_{context}']
= Disabling Telemetry in a CI environment

You can disable telemetry data collection while running {product-very-short} in a Continuous Integration (CI) environment.


.Prerequisites
* You have an administrator role in the {product-short}.
* You have installed the `janus-idp
-backstage-plugin-analytics-provider-segment` plugin in {product-short}. For more information, see link:{LinkAdminGuide}#rhdh-installing-dynamic-plugins[Dynamic plugin installation].

.Procedure

. Set the value of the `SEGMENT_TEST_MODE` environment variable to `true` in your CI configuration.
. Save the configuration changes.

14 changes: 0 additions & 14 deletions admin/proc-disabling-telemetry-in-CI-environments.adoc

This file was deleted.

25 changes: 25 additions & 0 deletions admin/proc-disabling-telemetry-in-local-environment.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
[id='disabling-telemetry-in-local-environment_{context}']
= Disabling Telemetry in a local environment

By default, the `analytics-provider-segment` plugin is disabled when you run the {product-short} application locally without using the `dynamic-plugins.default.yaml` file. However, if you run the application using the `dynamic-plugins.default.yaml` file, you can disable telemetry data collection based on your needs.

.Prerequisites
* You have an administrator role in the {product-short}.
* You have installed the `janus-idp
-backstage-plugin-analytics-provider-segment` plugin in {product-short}. For more information, see link:{LinkAdminGuide}#rhdh-installing-dynamic-plugins[Dynamic plugin installation].

.Procedure

. Add the following YAML code in your `dynamic-plugins.default.yaml` configuration file:
+
[source,yaml]
----
dynamicPlugins:
plugins:
- package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment'
disabled: true
----

. Save the configuration changes.

. Delete the `dynamic-plugins-root/janus-idp-backstage-plugin-analytics-provider-segment` plugin directory.
25 changes: 0 additions & 25 deletions admin/proc-disabling-telemetry-using-helm-chart.adoc

This file was deleted.

67 changes: 67 additions & 0 deletions admin/proc-disabling-telemetry.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
[id='disabling-telemetry-data-collection_{context}']
= Disabling Telemetry data collection in {product-very-short}

To disable telemetry data collection, you must configure the `analytics-provider-segment` plugin either using the Helm Chart or the {product} Operator.

[NOTE]
====
If the `analytics-provider-segment` plugin is already present in your Helm configuration file or ConfigMap file, set the value of the `plugins.disabled` parameter to `true` to quickly stop telemetry data collection.
====

.Prerequisites
* You have an administrator role in the {product-short}.
* You have installed the `janus-idp
-backstage-plugin-analytics-provider-segment` plugin in {product-short}. For more information, see link:{LinkAdminGuide}#rhdh-installing-dynamic-plugins[Dynamic plugin installation].

.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: true
----

+
.Using 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.

38 changes: 0 additions & 38 deletions admin/proc-enabling-telemetry-using-helm-chart.adoc

This file was deleted.

66 changes: 66 additions & 0 deletions admin/proc-enabling-telemetry.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
[id='enabling-telemetry-data-collection_{context}']
= Enabling Telemetry data collection in {product-very-short}

To enable telemetry data collection, you must configure the `analytics-provider-segment` plugin either using the Helm Chart or the {product} Operator.

[NOTE]
====
If the `analytics-provider-segment` plugin is already present in your Helm configuration file or ConfigMap file, set the value of the `plugins.disabled` parameter to `false` to quickly start telemetry data collection.
====

.Prerequisites
* You have an administrator role in the {product-short}.
* You have installed the `janus-idp
-backstage-plugin-analytics-provider-segment` plugin in {product-short}. For more information, see link:{LinkAdminGuide}#rhdh-installing-dynamic-plugins[Dynamic plugin installation].

.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 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.
6 changes: 3 additions & 3 deletions titles/admin-rhdh/title-admin.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,9 @@ include::installation/assembly-install-rhdh-ocp.adoc[leveloffset=+1]

include::modules/auth/assembly-enabling-authentication.adoc[leveloffset=+1]

//Telemetry data collection
include::admin/assembly-rhdh-telemetry.adoc[leveloffset=+1]

//aws integration
include::admin/assembly-rhdh-integration-aws.adoc[leveloffset=+1]

Expand All @@ -42,9 +45,6 @@ include::admin/ref-rbac-rest-api-endpoints.adoc[leveloffset=+3]
//Dynamic plugins
include::modules/dynamic-plugins/assembly-rhdh-installing-dynamic-plugins.adoc[leveloffset=+1]

//Telemetry data collection
include::admin/assembly-rhdh-telemetry.adoc[leveloffset=+1]

//== Dynamic plugins
:doc-show-dynamic-content: true

Expand Down

0 comments on commit cbd00b7

Please sign in to comment.