RHIDP-12524: Platform engineer define, name, and view aggregated KPIs for homepage#2183
RHIDP-12524: Platform engineer define, name, and view aggregated KPIs for homepage#2183rh-tokeefe wants to merge 11 commits into
Conversation
PR Build ResultsBuild passed -- 34/34 titles | 72s Content Quality AssessmentCQA Report
SummaryChecks: 19 total, 19 pass, 0 fail 19 checks: 19 pass, 0 fail Run Updated 2026-05-18 22:48:34 UTC |
rh-tokeefe
added
do-not-merge/work-in-progress
Technical review needed 🔩
PatAKnight
left a comment
PatAKnight
left a comment
There was a problem hiding this comment.
Couple of quick comments and then a comment here.
It seems like the task that is linked is for the aggregation feature: https://redhat.atlassian.net/browse/RHDHPLAN-411 which is more focused on the homepage cards and the ability to create new cards using the config. Whereas the feature: https://redhat.atlassian.net/browse/RHDHPLAN-915 was more of a focus on drilling down into those homepage cards to expose more information about the entities that went into making up that card. Overall the docs look good from the point of view the drill down feature. But probably does not capture the Configuring of KPIs with aggregated Scorecard data.
|
@PatAKnight I updated the existing procedure and added new topics based on your comments. |
PatAKnight
left a comment
PatAKnight
left a comment
There was a problem hiding this comment.
Alright, went in and did another review. Also going to tag @imykhno since he was the one that contributed the aggregation feature. Added some more review comments to help tighten up the docs a bit.
| [id="configure-aggregated-scorecard-kpis-to-monitor-the-health-of-multiple-applications_{context}"] | ||
| = Configure aggregated Scorecard KPIs to monitor the health of multiple applications |
There was a problem hiding this comment.
Same as the file rename. Something like "Drill down from aggregated Scorecard KPIs" could work.
There was a problem hiding this comment.
@PatAKnight the style guide would discourage the use of drill down. While the phrasing does appear in some section of doc, I think "View detailed metrics from aggregated scorecard KPIs" might align with style norms. Does that tile work ok?
PatAKnight
left a comment
PatAKnight
left a comment
There was a problem hiding this comment.
Looking pretty good, one final thing from me on one of the config values.
| [id="configure-aggregated-scorecard-kpis-to-monitor-the-health-of-multiple-applications_{context}"] | ||
| = Configure aggregated Scorecard KPIs to monitor the health of multiple applications |
imykhno
left a comment
imykhno
left a comment
There was a problem hiding this comment.
Thank you for preparing the documentation, it looks great! I would like to add a few comments on a couple of points that might not have been covered yet:
7.1. Monitor portfolio health with aggregated KPIs
I would like to ask you to update the endpoint (link to documentation) to the following: /aggregations/:aggregationId. During development we deprecated /metrics/:metricId/catalog/aggregations endpoint, added the information to the doc as well. What do you think should we update doc to new endpoint and say something about deprecated?
Configure portfolio health on a customizable home page
We also changed props for the dynamic plugin configuration file from the metricId to aggregationId. For this release the metricId in props is deprecated, it's still supported, however will be removed in future. What do you think should we also draw the customer's attention to this? And should we update all config examples metricId attribute to aggregationId to prevent using deprecated configurations? For example change to:
- mountPoint: home.page/cards
importName: ScorecardHomepageCard
config:
props:
aggregationId: "jira.open_issues"
layouts:
xl: { w: 3, h: 6 }
lg: { w: 4, h: 6 }
md: { w: 6, h: 6 }
sm: { w: 12, h: 6 }
xs: { w: 12, h: 6 }
xxs: { w: 12, h: 6 }7.11.2. API overview
Also I noticed that we have "API overview" and "API parameter details" chapters, should we also add information about new endpoints and update information about deprecated? If yes, this links may help:
I would say that short description for each endpoint should be enough. I like how GET /metrics endpoint info was formatted, you can take it as an example if needed.
Thank you for your time
There was a problem hiding this comment.
Want to clarify: am I right in understanding that this chapter explains how to configure an aggregated scorecard?
If so, I would recommend explaining how customers can configure:
- An aggregation card with a
default configuration:- In addition to using
app-config.yaml, the customer must provide a configuration to the dynamic plugin configuration file, as shown in the linked example. If you look at this config, theaggregationIdshould be used instead ofmetricId, which contains the metric value. For example:
- In addition to using
- mountPoint: home.page/cards
importName: ScorecardHomepageCard
config:
props:
aggregationId: "github.open_prs"
layouts:
xl: { w: 3, h: 6, x: 3 }
lg: { w: 4, h: 6, x: 4 }
md: { w: 6, h: 6, x: 6 }
sm: { w: 12, h: 6 }
xs: { w: 12, h: 6 }
xxs: { w: 12, h: 6 }- In case of using metricId value at the
aggregationIdattribute will be used default config. No extra configuration required only on the dynamic plugin configuration file configuration inapp-config.yamlis not needed. For more information use this doc - An aggregation card with the
statusGroupedtype:- To use this type customer should configure
app-config.yaml(scorecard.aggregationKPIs) and dynamic plugin configuration file (props.aggregationId). For more context I recommend you to read the whole information about Aggregation types in doc
- To use this type customer should configure
- An aggregation card with the
averagetype.- The same as for
statusGroupedtype
- The same as for
There was a problem hiding this comment.
I have updated the PR to reflect your suggestions.
There was a problem hiding this comment.
Thank you, I like the chapter descriptions!
| :_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 {product} instance. | ||
| * You have identified the `metricId` you wish to aggregate. | ||
|
|
||
| .Procedure | ||
|
|
||
| . Access your `app-config.yaml` file. | ||
|
|
||
| . Navigate to the `scorecard` section and add an `aggregationKPIs` block. | ||
|
|
||
| . 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: | ||
| + | ||
| [source,yaml] | ||
| ---- | ||
| scorecard: | ||
| aggregationKPIs: | ||
| openIssuesKpi: | ||
| title: 'Jira open issues KPI' | ||
| description: 'Open issues across entities you own, grouped by status.' | ||
| type: statusGrouped | ||
| metricId: jira.open_issues | ||
| ---- | ||
| + | ||
| where: | ||
| + | ||
| `scorecard.aggregationKPIs`:: Map of KPI keys to KPI definitions. Each key is an aggregation ID. For example `openIssuesKpi`. | ||
| `title`:: Title shown for the KPI. | ||
| `description`:: Short description of the KPI. | ||
| `type`:: Aggregation strategy. Use `statusGrouped` for counts per threshold status, or `average` for a weighted portfolio score. | ||
| `metricId`:: Metric provider ID. For example `jira.open_issues`, `github.open_prs`. | ||
|
|
||
| . Save the configuration and restart your {product} instance. | ||
|
|
||
| .Verification | ||
|
|
||
| . Navigate to the {product-short} homepage. | ||
|
|
||
| . Verify that the new aggregated card is displayed with the defined name and calculated value. No newline at end of file |
There was a problem hiding this comment.
I like this information. I would say that sub-chapter about "An aggregation card with the statusGrouped type" is ready. Only the description about type may be updated to describing only statusGrouped as we may want to have different sub-chapter for each types.
I would recommend use similar information for average type, but add information that:
options.statusScoresrequiredfor average type- map threshold rule keys (status keys for example success, warning, error) to numeric weights.
- Must be non-empty. Missing options / empty statusScores fails startup.
options.threshold:Optionalsame-shape number thresholds as metrics, evaluated against averageScore on 0–100 (one decimal).- If omitted, AverageAggregationStrategy uses built-in defaults: <30 error, 30–79 warning, ≥80 success (documented in aggregation.md and thresholds.md).
- If you do set thresholds, they must obey full real-line coverage (no gaps), same as number metric thresholds.
There was a problem hiding this comment.
added topics to PR to reflect this
|
@imykhno I have revised the PR based on your feedback. The current sprint ends May 19th. Ideally, I would like to try to merge this PR before the end of the sprint. Please review the PR when you are able to do so. |
| thresholds: | ||
| - max: 39 | ||
| status: error | ||
| - min: 40 | ||
| max: 74 | ||
| status: warning | ||
| - min: 75 | ||
| status: success |
There was a problem hiding this comment.
Please. use the following thresholds instead:
thresholds:
rules:
- key: success
expression: '>=80'
color: '#6bb300'
- key: warning
expression: '51-80'
color: 'rgb(224, 189, 108)'
- key: error
expression: '<51'
color: '#be1ec7'
- key: critical
expression: '<10'
color: '#ff0000' Threshold which I presented was tested in the application, this change will help provide a reliable configuration option for our users
There was a problem hiding this comment.
Thank you, I like the chapter descriptions!
rh-tokeefe
added
Technical review done ⛅
|
4 participants
IMPORTANT: Do Not Merge - To be merged by Docs Team Only
Merge to main and CP to release-1.10
Version(s):
1.10
Issue:
https://redhat.atlassian.net/browse/RHIDP-12524
Preview:
https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/pr-2183/observability_evaluate-project-health-using-scorecards/#configure-aggregated-scorecard-kpis-to-monitor-the-health-of-multiple-applications_monitor-collective-health-across-components
look for "Aggregated KPIs in the scorecard"