From 6a64308d525f5a27e2e585c439c4df82be98647d Mon Sep 17 00:00:00 2001 From: Tomas Kral Date: Mon, 20 May 2024 15:27:38 +0200 Subject: [PATCH] feat: configure Segment plugin to be able to send data to Red Hat (enabled by default) (#1028) * chore: enable and configure Segment plugin to start sending data * chore: modify CSP: allow loading script from cdn.segment.com * test * docs: add information about telemetry * chore(ci): set SEGMENT_TEST_MODE=true to disable Segment in CI * Update .ibm/pipelines/openshift-tests.sh Co-authored-by: Nick Boldt * Update .ibm/pipelines/openshift-tests.sh Co-authored-by: Nick Boldt * add sentence on how the telementry data is going to be used * fix rebase errors * Apply suggestions from code review Co-authored-by: Nick Boldt * switch segment plugin to disabled by default * add more documentation * Apply suggestions from code review Co-authored-by: Shipra Singh <94683525+shipsing@users.noreply.github.com> * apply more suggestions from code review * Apply suggestions from code review Co-authored-by: Nick Boldt * add suggestions from code review * remove removed openshift-tests.sh * Update getting-started.md * fix wording and formatting * enable telemetry by default * set SEGMENT_TEST_MODE=true in CI deployments * debug test * ci: use value_files instead of hack with yq --------- Co-authored-by: Nick Boldt Co-authored-by: Shipra Singh <94683525+shipsing@users.noreply.github.com> --- .ibm/images/Dockerfile | 7 +- .ibm/pipelines/openshift-ci-tests.sh | 1 + .../value_files/values_showcase-rbac.yaml | 4 +- .../value_files/values_showcase.yaml | 4 +- .rhdh/docker/Dockerfile | 5 + docker/Dockerfile | 4 + dynamic-plugins.default.yaml | 14 +- showcase-docs/getting-started.md | 149 ++++++++++++++++++ 8 files changed, 181 insertions(+), 7 deletions(-) diff --git a/.ibm/images/Dockerfile b/.ibm/images/Dockerfile index 925909968..3a640ea48 100644 --- a/.ibm/images/Dockerfile +++ b/.ibm/images/Dockerfile @@ -28,7 +28,7 @@ RUN echo "whoami: $(whoami)" \ # NPM does not need to be installed as it is already included with Node. && npm i -g yarn@latest \ # Show where Node loads required modules from - && node -p 'module.paths' + && node -p 'module.paths' # plus Electron and bundled Node versions RUN echo " node version: $(node -v) \n" \ @@ -50,7 +50,7 @@ RUN curl -fsSL https://clis.cloud.ibm.com/install/linux | sh && \ ENV GO_VERSION 1.19 ENV GO_SHA256 464b6b66591f6cf055bc5df90a9750bf5fbc9d038722bb84a9d56a2bea974be6 -# Install Go +# Install Go and other tools used by the pipeline RUN apt-get update && \ apt-get install -y curl && \ curl -LO "https://golang.org/dl/go${GO_VERSION}.linux-amd64.tar.gz" && \ @@ -75,6 +75,9 @@ RUN curl -fsSL -o /tmp/openshift-client-linux.tar.gz "https://mirror.openshift.c RUN apt-get update -y && \ apt-get install -y rsync +# Install yq +RUN wget https://github.com/mikefarah/yq/releases/download/v4.43.1/yq_linux_amd64.tar.gz -O - | tar xz && mv yq_linux_amd64 /usr/bin/yq + # Set environment variables to make Go work correctly ENV GOPATH /go ENV PATH $GOPATH/bin:/usr/local/go/bin:$PATH diff --git a/.ibm/pipelines/openshift-ci-tests.sh b/.ibm/pipelines/openshift-ci-tests.sh index b08e71ac1..8445342ce 100755 --- a/.ibm/pipelines/openshift-ci-tests.sh +++ b/.ibm/pipelines/openshift-ci-tests.sh @@ -1,6 +1,7 @@ #!/bin/sh set -e +set -x LOGFILE="test-log" JUNIT_RESULTS="junit-results.xml" diff --git a/.ibm/pipelines/value_files/values_showcase-rbac.yaml b/.ibm/pipelines/value_files/values_showcase-rbac.yaml index 5fe9e259e..88bd811c3 100644 --- a/.ibm/pipelines/value_files/values_showcase-rbac.yaml +++ b/.ibm/pipelines/value_files/values_showcase-rbac.yaml @@ -186,7 +186,9 @@ upstream: secretKeyRef: key: postgres-password name: '{{ .Release.Name }}-postgresql' - + # disable telemetry in CI + - name: SEGMENT_TEST_MODE + value: 'true' args: # This additional `app-config`` file is generated by the initContainer below, and contains the merged configuration of installed dynamic plugins. - '--config' diff --git a/.ibm/pipelines/value_files/values_showcase.yaml b/.ibm/pipelines/value_files/values_showcase.yaml index 4847473ef..bcf34f5a6 100644 --- a/.ibm/pipelines/value_files/values_showcase.yaml +++ b/.ibm/pipelines/value_files/values_showcase.yaml @@ -182,7 +182,9 @@ upstream: secretKeyRef: key: postgres-password name: '{{ .Release.Name }}-postgresql' - + # disable telemetry in CI + - name: SEGMENT_TEST_MODE + value: 'true' args: # This additional `app-config`` file is generated by the initContainer below, and contains the merged configuration of installed dynamic plugins. - '--config' diff --git a/.rhdh/docker/Dockerfile b/.rhdh/docker/Dockerfile index 62fea5d65..e52494b11 100644 --- a/.rhdh/docker/Dockerfile +++ b/.rhdh/docker/Dockerfile @@ -243,6 +243,11 @@ ENV CHOKIDAR_USEPOLLING='1' CHOKIDAR_INTERVAL='10000' # To avoid running scripts when using `npm pack` to install dynamic plugins ENV NPM_CONFIG_ignore-scripts='true' +# gGVM6sYRK0D0ndVX22BOtS7NRcxPej8t is key for dev environment +# Use production key in stable 1.yy.x branch; use dev key in main for CI/next builds +ENV SEGMENT_WRITE_KEY=gGVM6sYRK0D0ndVX22BOtS7NRcxPej8t +ENV SEGMENT_TEST_MODE=false + ENTRYPOINT ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.example.yaml", "--config", "app-config.example.production.yaml"] # append Brew metadata here diff --git a/docker/Dockerfile b/docker/Dockerfile index 8c32e5a79..2a66904be 100644 --- a/docker/Dockerfile +++ b/docker/Dockerfile @@ -146,6 +146,10 @@ ENV CHOKIDAR_USEPOLLING='1' CHOKIDAR_INTERVAL='10000' # To avoid running scripts when using `npm pack` to install dynamic plugins ENV NPM_CONFIG_ignore-scripts='true' +# Upstream only - Use dev key in all branches +ENV SEGMENT_WRITE_KEY=gGVM6sYRK0D0ndVX22BOtS7NRcxPej8t +ENV SEGMENT_TEST_MODE=false + ENTRYPOINT ["node", "packages/backend", "--config", "app-config.yaml", "--config", "app-config.example.yaml", "--config", "app-config.example.production.yaml"] # append Brew metadata here diff --git a/dynamic-plugins.default.yaml b/dynamic-plugins.default.yaml index 0b7b7f790..c5f4c3f58 100644 --- a/dynamic-plugins.default.yaml +++ b/dynamic-plugins.default.yaml @@ -325,7 +325,7 @@ plugins: gridColumn: '1 / -1' if: allOf: - - isArgocdConfigured + - isArgocdConfigured # Group: Azure Devops - package: ./dynamic-plugins/dist/backstage-plugin-scaffolder-backend-module-azure-dynamic @@ -842,17 +842,25 @@ plugins: props: width: 1500 height: 800 + - package: ./dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment - disabled: true + disabled: false pluginConfig: dynamicPlugins: frontend: janus-idp.backstage-plugin-analytics-provider-segment: apiFactories: - importName: SegmentAnalyticsApi + backend: + csp: + script-src: + - '''self''' + - '''unsafe-eval''' + - 'https://cdn.segment.com' app: analytics: segment: writeKey: ${SEGMENT_WRITE_KEY} - maskIP: ${SEGMENT_MASK_IP} # prevents IP addresses from being sent if true + maskIP: true # prevents IP addresses from being sent if true testMode: ${SEGMENT_TEST_MODE} # prevents data from being sent if true + diff --git a/showcase-docs/getting-started.md b/showcase-docs/getting-started.md index 5cee6b92f..c92e10bd2 100644 --- a/showcase-docs/getting-started.md +++ b/showcase-docs/getting-started.md @@ -2,6 +2,155 @@ There are several different methods for running the Backstage Showcase app today. We currently have support for running the application locally, using a helm chart to deploy to a cluster, and manifests for deployment using ArgoCD. +## Telemetry collection + +The telemetry data collection feature enhances your experience with the application without compromising your privacy. + +**Telemetry data collection is enabled by default.** + +To disable telemetry data collection, you need to disable the [`@janus-idp/backstage-plugin-analytics-provider-segment`](https://github.com/janus-idp/backstage-plugins/tree/main/plugins/analytics-provider-segment) plugin as documented below. + +- **Anonymous configuration**: + + - IP addresses are anonymized (`maskIP: true`), and recorded as `0.0.0.0`. + - `anonymousId` used for tracking is a hash derived from the user's username. + +- **Data Collection Overview**: + - **Events Tracked**: Page visits, clicks on links or buttons. + - **Common Data Points for All Events**: + - User-related info: locale, timezone, userAgent (browser and OS details). + - Page-related info: title, category, extension name, URL, path, referrer, search parameters. + +The telemetry data will only be used for internal analysis and product improvements. The collected data is analyzed to understand user interactions with the application while maintaining user anonymity and privacy. + +To enable or disable telemetry data collection and customize a telemetry destination, see the following sections. + +### Disable Telemetry + +To turn off the telemetry feature, you must disable the `analytics-provider-segment` plugin either using the Helm Chart or the RHDH Operator. + +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, or `false` to enable it. + +#### Using Helm Chart + +Add the following code in your Helm configuration file: + +```yaml +global: + dynamic: + plugins: + - package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment' + disabled: true +``` + +#### Using RHDH Operator + +When using RHDH Operator, you must modify the `ConfigMap` file created for dynamic plugin configuration. You specify the name of this `ConfigMap` file in the `dynamicPluginsConfigMapName` field of your `Backstage` custom resource. Usually, the `ConfigMap` file is named as `dynamic-plugins-rhdh`. +Add the following code to your `ConfigMap`` file: + +```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 +``` + +### Disable Telemetry for Local Development + +By default, the `analytics-provider-segment` plugin is disabled when you run your application locally without using the `dynamic-plugins.default.yaml` file. +However, if you run your application using the `dynamic-plugins.default.yaml` file, you can disable the `analytics-provider-segment` plugin as shown in the following example: + +```yaml +dynamicPlugins: + plugins: + - package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment' + disabled: true +``` + +Than delete the `dynamic-plugins-root/janus-idp-backstage-plugin-analytics-provider-segment` plugin directory, to stop plugin from loading. + +### Disabling Telemetry in Continuous Integration (CI) Environments + +To disable telemetry while running Backstage in a CI environment, set the value of the `SEGMENT_TEST_MODE` environment variable to `true`. This action deactivates telemetry transmissions. + +### Enable Telemetry + +To turn on the telemetry feature, you must enable the `analytics-provider-segment` plugin either using the Helm Chart or the RHDH Operator. + +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, or `true` to enable it. + +#### Using Helm Chart + +Add the following code in your Helm configuration file: + +```yaml +global: + dynamic: + plugins: + - package: './dynamic-plugins/dist/janus-idp-backstage-plugin-analytics-provider-segment' + disabled: false +``` + +#### Using RHDH Operator + +If you have created the `dynamic-plugins-rhdh` ConfigMap file as described in the [Configuring dynamic plugins with the Red Hat Developer Hub Operator](https://access.redhat.com/documentation/en-us/red_hat_developer_hub/1.1/html-single/administration_guide_for_red_hat_developer_hub/index#configuring-dynamic-plugins-with-the-red-hat-developer-hub-operator) section, add the `analytics-provider-segment` plugin to the list of plugins and set the `plugins.disabled` parameter to `true` to disable telemetry, or `false` to enable it. + +If you have not created the `dynamic-plugins-rhdh` ConfigMap file, create it with the following content: + +```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: + +```yaml +spec: + application: + dynamicPluginsConfigMapName: dynamic-plugins-rhdh +``` + +### Customizing Telemetry Destination + +By default, the `analytics-provider-segment` plugin is configured to send data to Red Hat. To change the destination that receives telemetry data, set the value of the `SEGMENT_WRITE_KEY` environment variable in your Helm configuration file as shown in the following examples. + +#### Example using Helm Chart + +```yaml +upstream: + backstage: + extraEnvVars: + - name: SEGMENT_WRITE_KEY + value: +``` + +#### Example using RHDH Operator + +```yaml +extraEnvs: + envs: + - name: SEGMENT_WRITE_KEY + value: +``` + +If you wish to subsequently disable telemetry data collection, use one of the following methods described below. + ## Running Locally with a basic configuration The easiest and fastest method for getting started: Backstage Showcase app, running it locally only requires a few simple steps.