Skip to content

Commit 6f08f37

Browse files
pabel-rhpabel-rh
committed
Scorecard plugin
1 parent 6713f2a commit 6f08f37

24 files changed

+673
-0
lines changed

‎assemblies/assembly-configuring-scorecards-in-rhdh.adoc‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
[id="assembly-configuring-scorecards-in-rhdh"]
4+
= Configuring Scorecards to view metrics in your {product} instance
5+
:context: assembly-configuring-scorecards-in-rhdh
6+
7+
You can configure metrics and scoring capabilities from various data sources for software components in the {product-very-short} catalog.
8+
9+
You can configure either of the following Scorecards in your {product-very-short} instance:
10+
* GitHub Scorecards
11+
* Jira Scorecards
12+
13+
include::modules/observe/scorecards/proc-configuring-github-scorecards-in-rhdh-instance.adoc[leveloffset=+1]
14+
15+
include::modules/observe/scorecards/proc-configuring-jira-scorecards-in-rhdh-instance.adoc[leveloffset=+1]

‎assemblies/assembly-scorecards-rhdh.adoc‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
[id="assembly-rhdh-observability"]
4+
= Understanding and visualizing {product} project health using Scorecards
5+
:context: assembly-scorecards-rhdh
6+
7+
include::modules/observe/scorecards/con-understand-scorecard-plugins.adoc[leveloffset=+1]
8+
9+
include::modules/observe/scorecards/con-supported-metrics-providers.adoc[leveloffset=+2]
10+
11+
include::assembly-setting-up-scorecards-to-monitor-your-rhdh-health.adoc[leveloffset=+1]
12+
13+
include::assembly-configuring-scorecards-in-rhdh.adoc[leveloffset=+1]
14+
15+
include::modules/observe/scorecards/con-manage-metric-thresholds-in-scorecard-plugin.adoc[leveloffset=+1]
16+
17+
include::modules/observe/scorecards/con-how-thresholds-work.adoc[leveloffset=+2]
18+
19+
include::modules/observe/scorecards/ref-supported-threshold-expressions.adoc[leveloffset=+2]
20+
21+
include::modules/observe/scorecards/ref-threshold-rules-to-metrics-for-scorecard-plugin.adoc[leveloffset=+2]
22+
23+
include::modules/observe/scorecards/con-set-global-standards-for-metric-thresholds.adoc[leveloffset=+2]
24+
25+
include::modules/observe/scorecards/ref-override-rules-to-configure-entity-specific-thresholds.adoc[leveloffset=+2]
26+
27+
include::modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc[leveloffset=+2]
28+
29+
include::modules/observe/scorecards/proc-viewing-scorecards-in-rhdh.adoc[leveloffset=+1]

‎assemblies/assembly-setting-up-scorecards-to-monitor-your-rhdh-health.adoc‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
3+
[id="assembly-setting-up-scorecards-to-monitor-your-rhdh-health"]
4+
= Setting up Scorecards to monitor your {product} project health
5+
:context: assembly-setting-up-scorecards-to-monitor-your-rhdh-health
6+
7+
include::modules/observe/scorecards/proc-installing-scorecard-plugin-in-rhdh-instance.adoc[leveloffset=+1]
8+
9+
include::modules/observe/scorecards/proc-authenticating-and-managing-scorecard-plugins.adoc[leveloffset=+1]

‎modules/observe/scorecards/artifacts/snip-developer-preview.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[IMPORTANT]
2+
====
3+
This section describes Developer Preview features in the Scorecard plugin. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA.
4+
5+
For more information about the support scope of Red Hat Developer Preview features, see https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope].
6+
====

‎modules/observe/scorecards/con-best-practices-for-threshold-rules.adoc‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-best-practices-for-threshold-rules"]
4+
= Best practices for threshold rules
5+
6+
Threshold rule evaluation is order-dependent. You must follow logical ordering to avoid unintended category assignments, as the system stops evaluation once a value matches the first rule.
7+
8+
== Follow logical ordering
9+
10+
Rules must be sequenced logically. Order rules from the most strict (smallest range) to the least strict (largest range) or ensure all ranges are mutually exclusive.
11+
12+
=== Problematic Rule Order Example
13+
14+
If rules are ordered incorrectly, a less restrictive rule can prevent stricter rules from being evaluated:
15+
16+
. `warning: <50`: Any value less than 50 triggers the warning rule and stops evaluation.
17+
. `success: <10`: This rule is not evaluated because all values less than 10 already matched the preceding warning rule.
18+
19+
=== Correct Ordering Example
20+
21+
Order the rules from the most restrictive value range to the least restrictive to ensure logical flow.
22+
+
23+
[source,yaml]
24+
----
25+
# Correct Example: Order from most restrictive (Error) to least restrictive (Success)
26+
rules:
27+
- key: error
28+
expression: '<10' # Only values below 10
29+
- key: warning
30+
expression: '10-50' # Only values between 10 and 50
31+
- key: success
32+
expression: '>50' # All remaining values above 50
33+
----

‎modules/observe/scorecards/con-how-thresholds-work.adoc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-how-thresholds-work_{context}"]
4+
= How Thresholds work
5+
6+
A threshold defines a condition or an expression that determines which visual category a metric value belongs to.
7+
8+
* Evaluation Order: Threshold rules are evaluated in the order they are defined. The first matching rule is applied to the metric value.
9+
* Allowed Categories: Only three keys are supported: `success`, `warning`, and `error`.
10+
* Best Practice: Always order rules from the most restrictive to the least restrictive to ensure logical assignment.

‎modules/observe/scorecards/con-manage-metric-thresholds-in-scorecard-plugin.adoc‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-manage-metric-thresholds-in-scorecard-plugin_{context}"]
4+
= Managing metric thresholds in your Scorecard plugin
5+
6+
The Scorecard plugin uses thresholds to translate raw metric values into visual health indicators (`Success`, `Warning`, or `Error`). Configuring these thresholds is the primary way platform engineers and developers define what constitutes a healthy component.

‎modules/observe/scorecards/con-set-global-standards-for-metric-thresholds.adoc‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-set-global-standards-to-configure-thresholds"]
4+
= Set global standards for metric thresholds
5+
6+
To override the default thresholds set by a metric provider, you must update your `{product-very-short} app-config.yaml` file under the configuration path of the specific metric.
7+
8+
The custom configuration completely replaces the provider's defaults. If you omit a threshold category (such as `success`), that category is not assigned unless it is explicitly overridden later by an entity annotation in the `catalog-info.yaml` file.
9+
10+
The following configuration defines a `success` threshold as 10 or fewer issues, which applies to all components using the `jira.open_issues` metric unless explicitly overridden by an entity annotation.
11+
+
12+
[source,yaml]
13+
----
14+
scorecard:
15+
plugins:
16+
jira:
17+
open_issues:
18+
thresholds:
19+
rules:
20+
- key: success
21+
expression: '<10' # fewer than 10 open issues is Success
22+
- key: warning
23+
expression: '10-50' # Between 10 and 50 is a Warning
24+
- key: error
25+
expression: '>50' # More than 50 open issues is an Error
26+
----

‎modules/observe/scorecards/con-supported-metrics-providers.adoc‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-supported-metric-providers_{context}"]
4+
= Supported metric providers in {product}
5+
6+
The Scorecard plugin collects metrics from third-party data sources using metric providers. The Scorecard node plugin provides the `scorecardMetricsExtensionPoint` extension point that is used to connect your backend plugin module that exports custom metrics via metric providers to the Scorecard backend plugin.
7+
8+
The following metric providers are available:
9+
10+
[cols="1,1,2,3,1", options="header"]
11+
|===
12+
| Provider | Metric ID | Title | Description | Type
13+
14+
| GitHub
15+
| `github.open_prs`
16+
| GitHub open PRs
17+
| Count of open Pull Requests in GitHub
18+
| number
19+
20+
| Jira
21+
| `jira.open_issues`
22+
| Jira open issues
23+
| The number of opened issues in Jira
24+
| number
25+
|===

‎modules/observe/scorecards/con-understand-scorecard-plugins.adoc‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
:_mod-docs-content-type: CONCEPT
2+
3+
[id="con-understand-scorecard-plugin_{context}"]
4+
= Understand Scorecard plugins in {product}
5+
6+
include::{docdir}/artifacts/snip-developer-preview.adoc[]
7+
8+
The Scorecard plugin offers comprehensive, customizable insights into the health, security posture, and compliance of your components, services, and APIs. It centralizes Key Performance Indicators (KPIs) within {product} ({product-very-short}), so you do not have to consult multiple external systems.

0 commit comments

Comments
 (0)