RHDHPAI-804: Multi-analytics provider (Adoption Insights plugin) (#1229)

* Incorporate changes

* Made a few changes

* Rebased branch and modularized content

* Incorporated Rohit's comments

* Incorporated Ben's comments except one

* Incorporated changes

* Minor change

* Added Karthik's comments

* Minor changes

* Incorporated some of Ben's comments

* Incorporated the rest of Ben's comments

* Incorporated Karthik's comments

* Combined the modifying topics together

* Incorporated Judy's comments

Author: pabel-rh

assemblies/assembly-adoption-insights.adoc

@@ -1,17 +1,30 @@
 [id="assembly-adoption-insights"]
 = Adoption Insights
 
-include::../artifacts/snip-developer-preview.adoc[]
+The {product} instance comes with the Adoption Insights plugin preinstalled and enabled by default.
 
-//about adoption insights
-include::modules/observe/adoption-insights/con-about-adoption-insights.adoc[leveloffset=+1]
+As organizations generate an increasing number of data events, there is a growing need for detailed insights into the adoption and engagement metrics of the internal developer portal. These insights help platform engineers make data-driven decisions to improve its performance, usability, and translate them into actionable insights. 
 
-//installing adoption insights
-include::modules/observe/adoption-insights/proc-install-adoption-insights.adoc[leveloffset=+1]
+You can use Adoption Insights in {product} to visualize key metrics and trends to get information about the usage of {product-short} in your organization. The information provided by Adoption Insights in {product-short} helps you pinpoint areas of improvement, highlights popular features, and evaluates progress toward adoption goals. You can also monitor user growth against licensed users and identify trends over time.
+
+The Adoption Insights dashboard in {product-short} includes the following cards:
+
+* *Active users*
+* *Total number of users*
+* *Top catalog entities*
+* *Top 3 templates*
+* *Top 3 techdocs*
+* *Top 3 plugins*
+* *Portal searches*
+
+image::rhdh-plugins-reference/adoption-insights.jpg[adoption insights]
 
 //configuring adoption insights
 include::modules/observe/adoption-insights/proc-configure-adoption-insights.adoc[leveloffset=+1]
 
+//disabling adoption insights
+include::modules/observe/adoption-insights/proc-customize-adoption-insights.adoc[leveloffset=+1]
+
 //using adoption insights
 include::modules/observe/adoption-insights/proc-using-adoption-insights.adoc[leveloffset=+1]
 
@@ -21,6 +34,18 @@ include::modules/observe/adoption-insights/proc-setting-duration-of-data-metrics
 //viewing cards
 include::modules/observe/adoption-insights/proc-viewing-adoption-insights-card.adoc[leveloffset=+1]
 
+include::modules/observe/adoption-insights/proc-viewing-active-users.adoc[leveloffset=+2]
+
+include::modules/observe/adoption-insights/proc-viewing-total-number-of-users.adoc[leveloffset=+2]
+
+include::modules/observe/adoption-insights/proc-viewing-top-catalog-entities.adoc[leveloffset=+2]
+
+include::modules/observe/adoption-insights/proc-viewing-top-templates.adoc[leveloffset=+2]
+
+include::modules/observe/adoption-insights/proc-viewing-top-techdocs.adoc[leveloffset=+2]
+
+include::modules/observe/adoption-insights/proc-viewing-top-plugins.adoc[leveloffset=+2]
+
 //modify number of displayed records
 include::modules/observe/adoption-insights/proc-modify-number-of-displayed-records.adoc[leveloffset=+1]
 

modules/observe/adoption-insights/con-about-adoption-insights.adoc

@@ -2,24 +2,4 @@
 [id="proc-configure-adoption-insights_{context}"]
 = Configuring the Adoption Insights plugin in {product}
 
-You can enable the Adoption Insights plugin by configuring the {product} Helm chart or the {product} Operator ConfigMap.
-
-.Procedure
-
-* To configure the Adoption Insights plugin in {product-short}, in your {product} `app-config.yaml` file, add the following code:
-+
-.`app-config.yaml` fragment
-[source,terminal]
-----
-app:
-  analytics:
-    adoptionInsights: 
-      maxBufferSize: 20 <1>
-      flushInterval: 5000 <2>
-      debug: false <3>
-      licensedUsers: 2000 <4>
-----
-<1> (Optional) Specifies the maximum buffer size for event batching. The default value is `20`. 
-<2> (Optional) Specifies the flush interval in milliseconds for event batching. The default value is `5000ms`.
-<3> (Optional) The default value is `false`.
-<4> (Optional) Specifies the maximum number of licensed users who can access the RHDH instance. The default value is `100`.
+The Adoption Insights plugin is preinstalled and enabled on a {product-short} instance by default. You can disable or enable the Adoption Insights plugin and change other parameters, by configuring the `app-config` ConfigMap, which is created by the {product} Helm chart or Operator.

modules/observe/adoption-insights/proc-configure-adoption-insights.adoc

@@ -0,0 +1,67 @@
+// Module included in the following assemblies:
+//
+// * assemblies/assembly-rhdh-observability.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="proc-customize-adoption-insights_{context}"]
+= Customizing the Adoption Insights plugin in {product}
+
+You can customize the Adoption Insights plugin to suit your needs by disabling or re-enabling it, and adjusting other settings as needed.
+
+
+[IMPORTANT]
+====
+If you used the developer preview of the Adoption Insights plugin and configured the feature manually, you must remove those earlier configuration changes as they are no longer required.
+
+In your dynamic plugins ConfigMap, for example: `dynamic-plugins-rhdh.yaml`, update the `package-disabled` value of the plugin to `false` as shown in the following example:
+
+.`dynamic-plugins.yaml` fragment
+[source,yaml]
+----
+plugins:
+  - package: ./dynamic-plugins/dist/backstage-community-plugin-analytics-provider-segment
+    disabled: false
+----
+====
+
+.Procedure
+
+* To customize `maxBufferSize`, `flushInterval`, `debug`, and `licensedUsers` in the Adoption Insights plugin, in your {product} `app-config.yaml` file, update the relevant settings as shown in the following code:
++
+.`app-config.yaml` fragment
+[source,terminal]
+----
+app:
+  analytics:
+    adoptionInsights: 
+      maxBufferSize: _<maximum_buffer_size>_ <1>
+      flushInterval: _<flush_interval>_ <2>
+      debug: _<debug_value>_ <3>
+      licensedUsers: _<licensed_users>_ <4>
+----
+<1> (Optional) Specifies the maximum buffer size for event batching. The default value is `20`. 
+<2> (Optional) Specifies the flush interval in milliseconds for event batching. The default value is `5000ms`.
+<3> (Optional) The default value is `false`.
+<4> (Optional) Specifies the maximum number of licensed users who can access the {product-very-short} instance. The default value is `100`.
+
+* To disable the Adoption Insights plugin, in your dynamic plugins ConfigMap, for example `dynamic-plugins-rhdh.yaml` file, update the `package.disabled` value of the plugin to `true` as shown in the following example:
++
+[source,yaml]
+----
+  - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-adoption-insights
+    disabled: true
+  - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-adoption-insights-backend-dynamic
+    disabled: true
+  - package: ./dynamic-plugins/dist/red-hat-developer-hub-backstage-plugin-analytics-module-adoption-insights-dynamic
+    disabled: true
+----
+
+* Optional: Configure the required RBAC permission for the users who are not administrators as shown in the following example:
++
+[source,yaml]
+----
+p, role:default/_<your_team>_, adoption-insights.events.read, read, allow
+g, user:default/_<your_user>_, role:default/_<your_team>_
+----
+See link:{authorization-book-url}#ref-rbac-permission-policies_title-authorization[Permission policies in {product}].
+

modules/observe/adoption-insights/proc-customize-adoption-insights.adoc

@@ -2,64 +2,24 @@
 [id="proc-modify-number-of-displayed-records_{context}"]
 = Modifying the number of displayed records
 
-== Modifying the number of displayed records in Top catalog entities
+You can modify the number of displayed records in Adoption Insights for the following cards.
 
-You can modify the number of records that are displayed in the *Top catalog entities* card. You can select any of the following number of records for display:
+* *Top catalog entities*
+* *Top 3 templates*
+* *Top 3 techdocs*
+* *Top 3 plugins*
 
-* *Top 3*
-* *Top 5*
-* *Top 10*
-* *Top 20*
-
-By default, the top three most viewed catalog entities are displayed. 
-
-.Procedure
-
-* Go to *Administration -> Adoption Insights* and click the *Down* arrow next to *3 rows* to change the number of displayed records.
-
-image::rhdh-plugins-reference/adoption-insights-catalog-entities.jpg[Catalog Entities dropdown]
-
-== Modifying the number of displayed records in Top 3 templates
-
-You can modify the number of records that are displayed in the *Top 3 templates* card. You can select any of the following number of records for display:
-
-* *Top 3*
-* *Top 5*
-* *Top 10*
-* *Top 20*
-
-By default, the top three most viewed templates are displayed. 
-
-.Procedure
-
-* Go to *Administration -> Adoption Insights* and click the *Down* arrow next to *3 rows* to change the number of displayed records.
-
-== Modifying the number of displayed records in Top 3 techdocs
-
-You can modify the number of records that are displayed in the *Top 3 techdocs* card. You can select any of the following number of records for display:
+You can select any of the following number of records for display:
 
 * *Top 3*
 * *Top 5*
 * *Top 10*
 * *Top 20*
 
-By default, the top three most viewed TechDocs are displayed. 
+By default, the top three most viewed catalog entities are displayed. 
 
 .Procedure
 
 * Go to *Administration -> Adoption Insights* and click the *Down* arrow next to *3 rows* to change the number of displayed records.
 
-== Modifying the number of displayed records in Top 3 plugins
-
-You can modify the number of records that are displayed in the *Top 3 plugins* card. You can select any of the following number of records for display:
-
-* *Top 3*
-* *Top 5*
-* *Top 10*
-* *Top 20*
-
-By default, the top three most viewed plugins are displayed. 
-
-.Procedure
-
-* Go to *Administration -> Adoption Insights* and click the *Down* arrow next to *3 rows* to change the number of displayed records.
+image::rhdh-plugins-reference/adoption-insights-catalog-entities.jpg[Catalog Entities dropdown]

modules/observe/adoption-insights/proc-install-adoption-insights.adoc

@@ -0,0 +1,19 @@
+:_mod-docs-content-type: PROCEDURE
+[id="proc-viewing-active-users_{context}"]
+= Viewing the active users
+
+The *Active users* card displays the total number of active users over a specified date and time period. You can export the user data in a .csv format.
+
+* *Returning users*: Existing users who have logged into {product-short} previously
+
+* *New users*: New users who have registered and logged into {product-short} for the first time
+
+image::rhdh-plugins-reference/active-users.jpg[active users]
+
+.Procedure
+
+* To view the list of active users in your {product} instance, go to *Administration -> Adoption Insights*, see the *Active users* card. 
+
+* To view the exact number of users for a particular day, hover over the corresponding date in the *Active users* card.
+
+* To export the user data in a .csv format, click the *Export CSV* link.