generated from redhat-developer/new-project-template
-
Notifications
You must be signed in to change notification settings - Fork 34
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
RHIDP-1908: Documenting the telemetry feature in admin guide (#212)
* RHIDP-1908: Documenting the telemetry feature in admin guide * Added detailed procedures * RHIDP-1908: minor content changes * incorporated SME comments * minor edit * Added a link to the telemetry section in air-gapped environment * fixed SME comments * Incorporated SME comments * Corrected the admin guide TOC * directory change * minor edit for clarity * minor edit for clarity * incorporated peer comments * minor edit * Update assemblies/assembly-rhdh-telemetry.adoc * Update assemblies/assembly-rhdh-telemetry.adoc switching back to on-by-default despite vigorous protests that this is a BAD IDEA and that we don't have proper approvals. --------- Co-authored-by: Nick Boldt <nboldt@redhat.com>
- Loading branch information
Showing
5 changed files
with
216 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
[id="assembly-rhdh-telemetry_{context}"] | ||
= Telemetry data collection | ||
|
||
The telemetry data collection feature is enabled by default. {product} sends telemetry data to Red Hat by using the `backstage-plugin-analytics-provider-segment` plugin. | ||
|
||
[IMPORTANT] | ||
==== | ||
You can disable the telemetry data collection feature based on your needs. For example, in an air-gapped environment, you can disable this feature to avoid needless outbound requests affecting the responsiveness of the {product-very-short} application. For more details, see the link:{LinkAdminGuide}#disabling-telemetry-data-collection_admin-rhdh[Disabling telemetry data collection in {product-very-short}] section. | ||
==== | ||
|
||
{company-name} analyzes the collected data to understand your interactions with the {product-very-short} application without disclosing your identity and compromising your privacy. {company-name} uses the collected data only for internal analysis and to improve the offerings and your experience with {product}. | ||
|
||
This feature collects the following data about your {product-very-short} usage: | ||
|
||
* Events of page visits and clicks on links or buttons. | ||
* System-related information, for example, locale, timezone, user agent including browser and OS details. | ||
* Page-related information, for example, title, category, extension name, URL, path, referrer, and search parameters. | ||
|
||
IP address and username are anonymized to maintain your privacy: | ||
|
||
* The IP addresses are anonymized and recorded as `0.0.0.0`. | ||
* The usernames are recorded as an anonymized hash. | ||
|
||
The username hash is a unique identifier that is used solely to identify the number of unique users of the {product-very-short} application. | ||
|
||
With {product-very-short}, you can customize the telemetry data collection feature and the telemetry Segment source configuration based on your needs. | ||
|
||
include::modules/admin/proc-disabling-telemetry.adoc[leveloffset=+1] | ||
|
||
include::modules/admin/proc-enabling-telemetry.adoc[leveloffset=+1] | ||
|
||
include::modules/admin/proc-customizing-telemetry-segment.adoc[leveloffset=+1] | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,49 @@ | ||
[id="customizing-telemetry-segment_{context}"] | ||
= Customizing telemetry Segment source | ||
|
||
|
||
The `analytics-provider-segment` plugin sends the collected telemetry data to {company-name} by default. However, you can configure a new Segment source that receives telemetry data based on your needs. For configuration, you need a unique Segment write key that points to the Segment source. | ||
|
||
[NOTE] | ||
==== | ||
By configuring a new Segment source, you can collect and analyze the same set of data that is mentioned in the link:{LinkAdminGuide}#assembly-rhdh-telemetry_admin-rhdh[Telemetry data collection] section. You might also require to create your own telemetry data collection notice for your application users. | ||
==== | ||
|
||
.Procedure | ||
|
||
. Configure integration with your Segment source by using one of the following options: | ||
+ | ||
.Using Helm Chart | ||
|
||
* Add the following YAML code in your Helm configuration file: | ||
+ | ||
[source,yaml] | ||
---- | ||
# ... | ||
upstream: | ||
backstage: | ||
extraEnvVars: | ||
- name: SEGMENT_WRITE_KEY | ||
value: <segment_key> # <1> | ||
# ... | ||
---- | ||
<1> `<segment_key>` denotes a unique identifier for your Segment source. | ||
|
||
+ | ||
.Using the Operator | ||
|
||
* Add the following YAML code in your `Backstage` custom resource (CR): | ||
+ | ||
[source,yaml] | ||
---- | ||
# ... | ||
extraEnvs: | ||
envs: | ||
- name: SEGMENT_WRITE_KEY | ||
value: <segment_key> # <1> | ||
# ... | ||
---- | ||
<1> `<segment_key>` denotes a unique identifier for your Segment source. | ||
|
||
. Save the configuration changes. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,66 @@ | ||
[id="disabling-telemetry-data-collection_{context}"] | ||
= Disabling telemetry data collection in {product-very-short} | ||
|
||
To disable telemetry data collection, you must disable the `analytics-provider-segment` plugin either using the Helm Chart or the {product} Operator configuration. | ||
|
||
[NOTE] | ||
==== | ||
If the `analytics-provider-segment` plugin is already present in your dynamic plugins configuration, set the value of the `plugins.disabled` parameter to `true` to disable telemetry data collection. | ||
==== | ||
|
||
.Procedure | ||
|
||
. Disable the `analytics-provider-segment` plugin by using one of the following options: | ||
+ | ||
.Using Helm Chart | ||
|
||
* Add the following YAML code in your Helm configuration file: | ||
+ | ||
[source,yaml] | ||
---- | ||
# ... | ||
global: | ||
dynamic: | ||
plugins: | ||
- package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment' | ||
disabled: true | ||
# ... | ||
---- | ||
|
||
+ | ||
.Using the Operator | ||
|
||
.. Perform one of the following steps: | ||
+ | ||
* If you have created the `dynamic-plugins-rhdh` ConfigMap file, add the `analytics-provider-segment` plugin to the list of plugins and set its `plugins.disabled` parameter to `true`. | ||
+ | ||
* If you have not created the ConfigMap file, create it with the following YAML code: | ||
+ | ||
[source,yaml] | ||
---- | ||
kind: ConfigMap | ||
apiVersion: v1 | ||
metadata: | ||
name: dynamic-plugins-rhdh | ||
data: | ||
dynamic-plugins.yaml: | | ||
includes: | ||
- dynamic-plugins.default.yaml | ||
plugins: | ||
- package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment' | ||
disabled: true | ||
---- | ||
|
||
.. Set the value of the `dynamicPluginsConfigMapName` parameter to the name of the ConfigMap file in your `Backstage` custom resource: | ||
+ | ||
[source,yaml] | ||
---- | ||
# ... | ||
spec: | ||
application: | ||
dynamicPluginsConfigMapName: dynamic-plugins-rhdh | ||
# ... | ||
---- | ||
|
||
. Save the configuration changes. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,65 @@ | ||
[id="enabling-telemetry-data-collection_{context}"] | ||
= Enabling telemetry data collection in {product-very-short} | ||
|
||
The telemetry data collection feature is enabled by default. However, if you have disabled the feature and want to re-enable it, you must enable the `analytics-provider-segment` plugin either by using the Helm Chart or the {product} Operator configuration. | ||
|
||
[NOTE] | ||
==== | ||
If the `analytics-provider-segment` plugin is already present in your dynamic plugins configuration, set the value of the `plugins.disabled` parameter to `false` to enable telemetry data collection. | ||
==== | ||
|
||
.Procedure | ||
|
||
. Configure the `analytics-provider-segment` plugin by using one of the following options: | ||
+ | ||
.Using Helm Chart | ||
|
||
* Add the following YAML code in your Helm configuration file: | ||
+ | ||
[source,yaml] | ||
---- | ||
# ... | ||
global: | ||
dynamic: | ||
plugins: | ||
- package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment' | ||
disabled: false | ||
# ... | ||
---- | ||
|
||
+ | ||
.Using the Operator | ||
|
||
.. Perform one of the following steps: | ||
+ | ||
* If you have created the `dynamic-plugins-rhdh` ConfigMap file, add the `analytics-provider-segment` plugin to the list of plugins and set its `plugins.disabled` parameter to `false`. | ||
+ | ||
* If you have not created the ConfigMap file, create it with the following YAML code: | ||
+ | ||
[source,yaml] | ||
---- | ||
kind: ConfigMap | ||
apiVersion: v1 | ||
metadata: | ||
name: dynamic-plugins-rhdh | ||
data: | ||
dynamic-plugins.yaml: | | ||
includes: | ||
- dynamic-plugins.default.yaml | ||
plugins: | ||
- package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment' | ||
disabled: false | ||
---- | ||
|
||
.. Set the value of the `dynamicPluginsConfigMapName` parameter to the name of the ConfigMap file in your `Backstage` custom resource: | ||
+ | ||
[source,yaml] | ||
---- | ||
# ... | ||
spec: | ||
application: | ||
dynamicPluginsConfigMapName: dynamic-plugins-rhdh | ||
# ... | ||
---- | ||
|
||
. Save the configuration changes. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters