RHIDP-12524: Platform engineer define, name, and view aggregated KPIs for homepage

Author: rh-tokeefe

assemblies/observability_evaluate-project-health-using-scorecards/assembly-monitor-collective-health-across-components.adoc

@@ -4,13 +4,18 @@ ifdef::context[:parent-context: {context}]
 [id="monitor-collective-health-across-components_{context}"]
 = Monitor collective health across components
 
-
 :context: monitor-collective-health-across-components
 [role="_abstract"]
 As an administrator, you can use the Scorecard plugin to view the collective technical health across multiple owned applications or components. This consolidated view helps you identify high-level health trends and risks across complex projects.
 
 include::../modules/observability_evaluate-project-health-using-scorecards/con-monitor-portfolio-health-with-aggregated-kpis.adoc[leveloffset=+1]
 
+include::../modules/observability_evaluate-project-health-using-scorecards/con-aggregated-kpis-in-the-scorecard.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-aggregated-kpis-for-the-scorecard.adoc[leveloffset=+1]
+
+include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-aggregated-scorecard-kpis-to-monitor-the-health-of-multiple-applications.adoc[leveloffset=+1]
+
 include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-customizable-home-page.adoc[leveloffset=+1]
 
 include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-read-only-home-page.adoc[leveloffset=+1]

modules/observability_evaluate-project-health-using-scorecards/con-aggregated-kpis-in-the-scorecard.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="aggregated-kpis-in-the-scorecard_{context}"]
+= Aggregated KPIs in the scorecard
+
+[role="_abstract"]
+Monitor the technical health and regulatory compliance of your infrastructure by using aggregated Key Performance Indicators (KPIs). These KPIs summarize complex data from multiple entities into a high-level overview, allowing you to identify system risks quickly.
+
+Aggregated KPIs allow engineering and product managers to monitor the collective status of all components or applications owned by a specific group in the Software Catalog. Instead of manually inspecting individual service scorecards, managers can use these metrics to identify broad trends or risks within their portfolio.
+
+Aggregated metrics rely on the `owner` field defined in the Software Catalog entities to determine which data points to include. The scorecard plugin performs scheduled batch processing to calculate these values; therefore, aggregated data is not updated in real-time.
+
+The plugin supports simple aggregation logic, such as summing values (SUM) or calculating averages (AVERAGE) across entities. 

modules/observability_evaluate-project-health-using-scorecards/proc-configure-aggregated-kpis-for-the-scorecard.adoc

@@ -0,0 +1,49 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="configure-aggregated-kpis-for-the-scorecard_{context}"]
+= Configure aggregated KPIs for the scorecard
+
+[role="_abstract"]
+Define aggregated Key Performance Indicators (KPIs) in your configuration to provide a consolidated view of team or group health. Aggregating KPIs allows you to summarize technical metrics into high-level insights for management and stakeholders.
+
+.Prerequisites
+* The scorecard plugin is installed and configured in your Red Hat Developer Hub instance.
+* You have identified the `metricId` and the `owner` group from the Software Catalog you wish to aggregate.
+
+.Procedure
+
+. Access your `app-config.yaml` file.
+
+. Navigate to the `scorecard` section and add an `aggregations` block.
+
+. Update the configuration to create a homepage card that summarizes a specific metric for a team portfolio. The following example calculates the total bug count for all components owned by Team Alpha:
++
+[source,yaml]
+----
+scorecard:
+  aggregations:
+    - id: team-alpha-total-bugs
+      name: "Total Open Bugs (Team Alpha)"
+      description: "Aggregated sum of Jira bugs across all Team Alpha components"
+      type: sum
+      metricId: jira.open_bugs
+      selector:
+        owner: group:default/team-alpha
+----
++
+where:
++
+`scorecard.aggregations.id`:: Specifies a unique identifier for the aggregated KPI.
+`scorecard.aggregations.name`:: Specifies the name displayed on the homepage card.
+`scorecard.aggregations.description`:: Specifies A brief explanation of what the metric represents.
+`scorecard.aggregations.type`:: Specifies the aggregation function. Supported values include `sum` and `average`.
+`scorecard.aggregations.metricId`:: Specifies the ID of the source metric from individual scorecards.
+`scorecard.aggregations.selector`:: Specifies the criteria used to group entities, typically defined by `owner`.
+
+. Save the configuration and restart your Red Hat Developer Hub instance. [cite: 5360, 3931]
+
+.Verification
+
+. Navigate to the {product-short} homepage.
+
+. Verify that the new aggregated card is displayed with the defined name and calculated value.

modules/observability_evaluate-project-health-using-scorecards/proc-configure-aggregated-scorecard-kpis-to-monitor-the-health-of-multiple-applications.adoc

@@ -0,0 +1,61 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="configure-aggregated-scorecard-kpis-to-monitor-the-health-of-multiple-applications_{context}"]
+= Configure aggregated Scorecard KPIs to monitor the health of multiple applications
+
+[role="_abstract"]
+Configure the {product} Scorecard plugin to enable drill-down capabilities. This allows you to investigate the specific catalog entities and metrics that contribute to aggregated KPI scores, helping to identify and troubleshoot failing applications across a portfolio.
+
+.Prerequisites
+
+* You have installed {product}.
+* You have configured at least one Scorecard metric provider, such as GitHub or Jira.
+* You have configured aggregated KPIs.
+
+.Procedure
+
+. Define the metric ID for drill-down in your `app-config.yaml` file. 
++
+Drill-downs are metric-scoped. Even when you click an aggregated KPI, the system requires the underlying `metricId` to query the catalog for related entities.
++
+[source,yaml]
+----
+jira:
+  product: cloud
+  baseUrl: ${JIRA_URL}
+  token: ${JIRA_TOKEN} 
+jira:
+  product: cloud
+  baseUrl: ${JIRA_URL}
+  token: ${JIRA_TOKEN}      
+scorecard:
+  plugins:
+    jira:
+      open_issues:
+        schedule:
+          frequency: { minutes: 5 }
+          timeout: { minutes: 10 }
+          initialDelay: { seconds: 10 }
+----
+
+. Configure Role-Based Access Control (RBAC) permissions for the relevant user roles to enable scorecard access.
+
+.. Open your RBAC policy file, typically `rbac-policy.csv`.
+
+.. Add the following permission to read both scorecard metrics and catalog entities.
++
+[source,csv]
+----
+p, role:default/team_lead, scorecard.metric.read, read, allow
+p, role:default/team_lead, catalog.entity.read, read, allow
+----
+
+.Verification
+
+.. Navigate to the {product} Home Page.
+
+.. Click an aggregated KPI tile, such as *Critical Jira Issues*.
+
+.. Verify that a list of individual catalog entities appears, showing the components contributing to that aggregate score.
++
+If the list does not appear, ensure you are using the latest version of the {product-very-short} plugins.