Skip to content

Commit 21cdb91

Browse files
openshift-cherrypick-robotrh-tokeefe
openshift-cherrypick-robot
and
rh-tokeefe
authored
[release-1.10] RHIDP-12524: Platform engineer define, name, and view aggregated KPIs for homepage (#2272)
* RHIDP-12524: Platform engineer define, name, and view aggregated KPIs for homepage * RHIDP-12524: updated files based on dev review of the additional topics * RHIDP-12524: minor edit * RHIDP-12524: edits from dev review. added new topics * RHIDP-12524: submitting fixes for CQA faliures * RHIDP: more additions from dev review * RHIDP-12524: had to break assembly because it contained more than 15 items * RHIDP-12524: updated titles file to include new assembly * RHIDP-12524: minor edit * RHIDP-12524: updated threshold based on dev feebdack * RHIDP-12524: updated assembly to use attribute --------- Co-authored-by: Tim O'Keefe <tokeefe@redhat.com>
1 parent f4735e4 commit 21cdb91

11 files changed

Lines changed: 382 additions & 3 deletions

‎assemblies/observability_evaluate-project-health-using-scorecards/assembly-configure-scorecard-cards-on-the-homepage.adoc‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
ifdef::context[:parent-context: {context}]
3+
4+
[id="configure-scorecard-cards-on-the-homepage_{context}"]
5+
= Configure scorecard cards on the homepage
6+
7+
:context: configure-scorecard-cards-on-the-homepage
8+
9+
[role="_abstract"]
10+
Scorecard visualization cards on the {product} homepage display aggregated metrics to give engineering managers and platform teams immediate visibility into portfolio health trends.
11+
12+
include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-a-default-scorecard-aggregation-card.adoc[leveloffset=+1]
13+
14+
include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-a-status-grouped-tracking-type.adoc[leveloffset=+1]
15+
16+
include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-an-average-tracking-type.adoc[leveloffset=+1]
17+
18+
include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-customizable-home-page.adoc[leveloffset=+1]
19+
20+
include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-read-only-home-page.adoc[leveloffset=+1]
21+
22+
ifdef::parent-context[:context: {parent-context}]
23+
ifndef::parent-context[:!context:]

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

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,16 +4,17 @@ ifdef::context[:parent-context: {context}]
44
[id="monitor-collective-health-across-components_{context}"]
55
= Monitor collective health across components
66

7-
87
:context: monitor-collective-health-across-components
98
[role="_abstract"]
109
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.
1110

1211
include::../modules/observability_evaluate-project-health-using-scorecards/con-monitor-portfolio-health-with-aggregated-kpis.adoc[leveloffset=+1]
1312

14-
include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-customizable-home-page.adoc[leveloffset=+1]
13+
include::../modules/observability_evaluate-project-health-using-scorecards/con-aggregated-kpis-in-the-scorecard.adoc[leveloffset=+1]
14+
15+
include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-aggregated-kpis-for-the-scorecard.adoc[leveloffset=+1]
1516

16-
include::../modules/observability_evaluate-project-health-using-scorecards/proc-configure-portfolio-health-on-a-read-only-home-page.adoc[leveloffset=+1]
17+
include::../modules/observability_evaluate-project-health-using-scorecards/proc-view-detailed-metrics-from-aggregated-scorecard-kpis.adoc[leveloffset=+1]
1718

1819
include::../modules/observability_evaluate-project-health-using-scorecards/proc-schedule-metrics-to-avoid-api-limits.adoc[leveloffset=+1]
1920

@@ -24,5 +25,10 @@ include::../modules/observability_evaluate-project-health-using-scorecards/ref-e
2425
include::../modules/observability_evaluate-project-health-using-scorecards/proc-view-aggregated-metrics-for-owned-entities.adoc[leveloffset=+1]
2526

2627
include::../modules/observability_evaluate-project-health-using-scorecards/ref-available-metric-data-for-entities.adoc[leveloffset=+1]
28+
29+
include::../modules/observability_evaluate-project-health-using-scorecards/ref-scorecard-card-configuration-parameters.adoc[leveloffset=+1]
30+
31+
include::../modules/observability_evaluate-project-health-using-scorecards/ref-scorecard-plugin-rest-api-endpoints-and-parameters.adoc[leveloffset=+1]
32+
2733
ifdef::parent-context[:context: {parent-context}]
2834
ifndef::parent-context[:!context:]

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="aggregated-kpis-in-the-scorecard_{context}"]
4+
= Aggregated KPIs in the scorecard
5+
6+
[role="_abstract"]
7+
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.
8+
9+
Aggregated KPIs allow engineering and product managers to monitor the collective status of all entities the viewer owns 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.
10+
11+
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.
12+
13+
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-a-default-scorecard-aggregation-card.adoc‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="configure-a-default-scorecard-aggregation-card_{context}"]
4+
= Configure a default scorecard aggregation card
5+
6+
[role="_abstract"]
7+
Add a standard scorecard summary card to your homepage using default, out-of-the-box configurations.
8+
9+
.Prerequisites
10+
11+
* The scorecard plugin is installed and configured in your {product} instance.
12+
13+
* You have administrator permissions to update application configuration files.
14+
15+
.Procedure
16+
. Open your dynamic plugin configuration file.
17+
18+
. Navigate to your scorecard card block under the `home.page/cards` mount point.
19+
20+
. Update the configuration to use the `aggregationId` property with an established system metric name:
21+
+
22+
[source,yaml]
23+
----
24+
- mountPoint: home.page/cards
25+
importName: ScorecardHomepageCard
26+
config:
27+
props:
28+
aggregationId: "github.open_prs"
29+
layouts:
30+
xl: { w: 3, h: 6, x: 3 }
31+
lg: { w: 4, h: 6, x: 4 }
32+
md: { w: 6, h: 6, x: 6 }
33+
sm: { w: 12, h: 6 }
34+
xs: { w: 12, h: 6 }
35+
xxs: { w: 12, h: 6 }
36+
----
37+
38+
. Save the modified configuration file and restart your {product} instance.
39+
40+
.Verification
41+
. Access your {product-short} homepage interface.
42+
. Verify that the standard scorecard summary card displays with default metrics.

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

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="configure-aggregated-kpis-for-the-scorecard_{context}"]
4+
= Configure aggregated KPIs for the scorecard
5+
6+
[role="_abstract"]
7+
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.
8+
9+
.Prerequisites
10+
* The scorecard plugin is installed and configured in your {product} instance.
11+
* You have identified the `metricId` you wish to aggregate.
12+
13+
.Procedure
14+
15+
. Access your `app-config.yaml` file.
16+
17+
. Navigate to the `scorecard` section and add an `aggregationKPIs` block.
18+
19+
. Update the configuration to create a homepage card that summarizes a specific metric for a team portfolio. The following example adds a Jira open issues card that groups counts by threshold status for the entities that the signed-in user owns:
20+
+
21+
[source,yaml]
22+
----
23+
scorecard:
24+
aggregationKPIs:
25+
openIssuesKpi:
26+
title: 'Jira open issues KPI'
27+
description: 'Open issues across entities you own, grouped by status.'
28+
type: statusGrouped
29+
metricId: jira.open_issues
30+
----
31+
+
32+
where:
33+
+
34+
`scorecard.aggregationKPIs`:: Map of KPI keys to KPI definitions. Each key is an aggregation ID. For example `openIssuesKpi`.
35+
`title`:: Title shown for the KPI.
36+
`description`:: Short description of the KPI.
37+
`type`:: Aggregation strategy. Use `statusGrouped` for counts per threshold status, or `average` for a weighted portfolio score.
38+
`metricId`:: Metric provider ID. For example `jira.open_issues`, `github.open_prs`.
39+
40+
. Save the configuration and restart your {product} instance.
41+
42+
.Verification
43+
44+
. Navigate to the {product-short} homepage.
45+
46+
. Verify that the new aggregated card is displayed with the defined name and calculated value.

‎modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-a-status-grouped-tracking-type.adoc‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="configure-an-aggregation-card-with-a-status-grouped-tracking-type_{context}"]
4+
= Configure an aggregation card with a status-grouped tracking type
5+
6+
[role="_abstract"]
7+
Configure a scorecard aggregation card to count entities based on status thresholds.
8+
9+
.Prerequisites
10+
11+
* The scorecard plugin is installed and configured in your {product} instance.
12+
13+
.Procedure
14+
. Open your `app-config.yaml` file.
15+
16+
. Navigate to the `scorecard` section and define your backend Key Performance Indicator (KPI) map within an `aggregationKPIs` block, setting the tracking type to `statusGrouped`:
17+
+
18+
[source,yaml]
19+
----
20+
scorecard:
21+
aggregationKPIs:
22+
team-alpha-bugs:
23+
title: "Team Alpha Bug KPI"
24+
description: "Portfolio bug counts grouped by status threshold"
25+
type: statusGrouped
26+
metricId: jira.open_issues
27+
----
28+
. Open your dynamic plugin configuration file.
29+
30+
. Reference your custom aggregation ID inside the homepage card properties block under the `home.page/cards` mount point:
31+
+
32+
[source,yaml]
33+
----
34+
- mountPoint: home.page/cards
35+
importName: ScorecardHomepageCard
36+
config:
37+
props:
38+
aggregationId: "team-alpha-bugs"
39+
layouts:
40+
xl: { w: 3, h: 6 }
41+
lg: { w: 4, h: 6 }
42+
md: { w: 6, h: 6 }
43+
sm: { w: 12, h: 6 }
44+
xs: { w: 12, h: 6 }
45+
xxs: { w: 12, h: 6 }
46+
----
47+
48+
. Save the modified configuration files and restart your {product} instance.
49+
50+
.Verification
51+
. Access your {product-short} homepage interface.
52+
. Verify that the status-grouped scorecard summary card displays with your defined title and calculations.

‎modules/observability_evaluate-project-health-using-scorecards/proc-configure-an-aggregation-card-with-an-average-tracking-type.adoc‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
[id="configure-an-aggregation-card-with-an-average-tracking-type_{context}"]
3+
= Configure an aggregation card with an average tracking type
4+
5+
[role="_abstract"]
6+
Configure a scorecard aggregation card to calculate a single weighted portfolio score across multiple components.
7+
8+
.Prerequisites
9+
* The scorecard plugin is installed and configured in your Red Hat Developer Hub instance.
10+
11+
.Procedure
12+
13+
. Open your `app-config.yaml` file.
14+
15+
. Navigate to the `scorecard` section and define your backend Key Performance Indicator (KPI) map within an `aggregationKPIs` block, setting the tracking type to `average`.
16+
17+
. Add the required `statusScores` map to bind numeric weights to your status rules:
18+
+
19+
[source,yaml]
20+
----
21+
scorecard:
22+
aggregationKPIs:
23+
portfolio-average-health:
24+
title: "Portfolio Health KPI"
25+
description: "Weighted average score across portfolio components"
26+
type: average
27+
metricId: github.open_prs
28+
options:
29+
statusScores:
30+
success: 100
31+
warning: 50
32+
error: 0
33+
----
34+
35+
. Optional: To override the built-in system defaults, add custom threshold parameters using a continuous, gapless number range evaluated on a scale of `0` to `100`:
36+
+
37+
[source,yaml]
38+
----
39+
options:
40+
statusScores:
41+
success: 100
42+
warning: 50
43+
error: 0
44+
thresholds:
45+
rules:
46+
- key: success
47+
expression: '>=80'
48+
color: '#6bb300'
49+
- key: warning
50+
expression: '51-80'
51+
color: 'rgb(224, 189, 108)'
52+
- key: error
53+
expression: '<51'
54+
color: '#be1ec7'
55+
- key: critical
56+
expression: '<10'
57+
color: '#ff0000'
58+
----
59+
60+
. Open your dynamic plugin configuration file.
61+
62+
. Reference your average tracking aggregation ID inside the homepage card properties block under the `home.page/cards` mount point:
63+
+
64+
[source,yaml]
65+
----
66+
- mountPoint: home.page/cards
67+
importName: ScorecardHomepageCard
68+
config:
69+
props:
70+
aggregationId: "portfolio-average-health"
71+
layouts:
72+
xl: { w: 3, h: 6 }
73+
lg: { w: 4, h: 6 }
74+
md: { w: 6, h: 6 }
75+
sm: { w: 12, h: 6 }
76+
xs: { w: 12, h: 6 }
77+
xxs: { w: 12, h: 6 }
78+
----
79+
80+
. Save the modified configuration files and restart your {product} instance.
81+
82+
.Verification
83+
. Access your {product-short} homepage interface.
84+
. Verify that the weighted average scorecard summary card displays with your custom scores and thresholds.

‎modules/observability_evaluate-project-health-using-scorecards/proc-view-detailed-metrics-from-aggregated-scorecard-kpis.adoc‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
:_mod-docs-content-type: PROCEDURE
2+
3+
[id="view-detailed-metrics-from-aggregated-scorecard-kpis_{context}"]
4+
= View detailed metrics from aggregated scorecard KPIs
5+
6+
[role="_abstract"]
7+
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.
8+
9+
.Prerequisites
10+
11+
* You have installed {product}.
12+
* You have configured at least one Scorecard metric provider, such as GitHub or Jira.
13+
* You have configured aggregated KPIs.
14+
15+
.Procedure
16+
17+
. Define the metric ID for drill-down in your `app-config.yaml` file.
18+
+
19+
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.
20+
+
21+
[source,yaml]
22+
----
23+
jira:
24+
product: cloud
25+
baseUrl: ${JIRA_URL}
26+
token: ${JIRA_TOKEN}
27+
scorecard:
28+
plugins:
29+
jira:
30+
open_issues:
31+
schedule:
32+
frequency: { minutes: 5 }
33+
timeout: { minutes: 10 }
34+
initialDelay: { seconds: 10 }
35+
----
36+
37+
. Configure Role-Based Access Control (RBAC) permissions for the relevant user roles to enable scorecard access.
38+
39+
.. Open your RBAC policy file, typically `rbac-policy.csv`.
40+
41+
.. Add the following permission to read both scorecard metrics and catalog entities.
42+
+
43+
[source,csv]
44+
----
45+
p, role:default/team_lead, scorecard.metric.read, read, allow
46+
p, role:default/team_lead, catalog.entity.read, read, allow
47+
----
48+
49+
.Verification
50+
51+
.. Navigate to the {product} Home Page.
52+
53+
.. Click an aggregated KPI tile, such as *Critical Jira Issues*.
54+
55+
.. Verify that a list of individual catalog entities appears, showing the components contributing to that aggregate score.
56+
+
57+
If the list does not appear, ensure you are using the latest version of the {product-very-short} plugins.

‎modules/observability_evaluate-project-health-using-scorecards/ref-scorecard-card-configuration-parameters.adoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
:_mod-docs-content-type: REFERENCE
2+
3+
[id="scorecard-card-configuration-parameters_{context}"]
4+
= Scorecard card configuration parameters
5+
6+
[role="_abstract"]
7+
Parameters for application settings and dynamic plugin files used to manage homepage visualizations and portfolio data logic.
8+
9+
== Dynamic plugin properties
10+
[cols="1,3",options="header"]
11+
|===
12+
|Property |Description
13+
|`aggregationId` |The target identifier for the homepage visualization block. Accepts a default system metric name string or a custom KPI key mapped in your core settings.
14+
|`metricId` |[Deprecated] Legacy identifier for the source metric string. Supported for backwards compatibility but scheduled for removal in a future release. Replace with `aggregationId`.
15+
|===
16+
17+
== Application configuration properties (`scorecard.aggregationKPIs`)
18+
[cols="1,3",options="header"]
19+
|===
20+
|Property |Description
21+
|`title` |The primary textual label rendered on the header block of the homepage card.
22+
|`description` |A brief text string summarizing the target scope of the KPI.
23+
|`type` |The structural tracking strategy. Specify `statusGrouped` to return independent numerical entity counts per threshold status layer, or specify `average` to calculate a single weighted portfolio score.
24+
|`metricId` |The unique provider identifier mapping to the individual source plugin collection layer.
25+
|===
26+
27+
== Options parameters for the `average` tracking type
28+
`options.statusScores`:: Map of threshold status rule keys (`success`, `warning`, `error`) to numeric weight integers. This parameter is required for the `average` type and must be non-empty; missing or empty maps cause application startup failures.
29+
`options.thresholds`:: Optional numeric value array tracking custom status levels evaluated against the `averageScore` output value on a scale from 0 to 100 with one decimal place. If omitted, the system falls back to default values: less than 30 indicates an error, 30 to 79 indicates a warning, and 80 or higher indicates a success. Custom configurations must provide full real-line range coverage with no numeric gaps.

0 commit comments

Comments
 (0)