From f9d350fb86d2fe55ff3c06b4907de859de846429 Mon Sep 17 00:00:00 2001 From: Gerry-Forde Date: Tue, 29 Apr 2025 00:24:11 +0100 Subject: [PATCH 1/7] RHIDP-5421 - Document which plugins in RHDH have metrics --- .../keycloak/keycloak-plugin-admin.adoc | 39 +++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc index d456e06c28..9049a2d87a 100644 --- a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc +++ b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc @@ -143,6 +143,45 @@ When using client credentials, the access type must be set to `confidential` and * `query-users` * `view-users` +== Metrics + +The Keycloak backend plugin supports link:https://opentelemetry.io/[OpenTelemetry] metrics to monitor fetch operations and diagnose potential issues. + +=== Available Counters + +.Keycloak metrics +[cols="50%,50%", frame="all", options="header"] +|=== +|Metric Name +|Description +| `backend_keycloak_fetch_task_failure_count_total` | Counts fetch task failures where no data was returned due to an error. +| `backend_keycloak_fetch_data_batch_failure_count_total` | Counts partial data batch failures. Even if some batches fail, the plugin continues fetching others. +|=== + +=== Labels + +All counters include the `taskInstanceId` label, which uniquely identifies each scheduled fetch task. This allows you to trace failures back to individual task executions. For example: + +[source,subs="+attributes,+quotes"] +---- +backend_keycloak_fetch_data_batch_failure_count_total{taskInstanceId="df040f82-2e80-44bd-83b0-06a984ca05ba"} 1 +---- + +// === Use Case Example + +// Imagine your Keycloak instance is under-provisioned (e.g., low CPU/RAM limits), and the plugin is configured to send many parallel API requests. +// This could cause request timeouts or throttling. The metrics described above can help detect such behavior early, allowing administrators to: + +// - Tune the plugin configuration (e.g., reduce parallelism) +// - Increase resources on the Keycloak server +// - Investigate network or permission issues + +=== Exporting Metrics + +You can export metrics using any OpenTelemetry-compatible backend, such as *Prometheus*. + +See the link:https://backstage.io/docs/tutorials/setup-opentelemetry[Backstage OpenTelemetry setup guide] for integration instructions. + == Limitations If you have self-signed or corporate certificate issues, you can set the following environment variable before starting {product-short}: From 0f801dd99e3c450efa868672d3b1a527e0870d5b Mon Sep 17 00:00:00 2001 From: Gerry-Forde <63045020+Gerry-Forde@users.noreply.github.com> Date: Mon, 5 May 2025 20:16:34 +0100 Subject: [PATCH 2/7] Update artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc Co-authored-by: Lindsey Frazier --- .../rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc index 9049a2d87a..e75cd18aee 100644 --- a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc +++ b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc @@ -145,7 +145,7 @@ When using client credentials, the access type must be set to `confidential` and == Metrics -The Keycloak backend plugin supports link:https://opentelemetry.io/[OpenTelemetry] metrics to monitor fetch operations and diagnose potential issues. +The Keycloak backend plugin supports link:https://opentelemetry.io/[OpenTelemetry] metrics that you can use to monitor fetch operations and diagnose potential issues. === Available Counters From 2c5526f1fc92137ff32a0b9310e760f92e0ac515 Mon Sep 17 00:00:00 2001 From: Gerry-Forde <63045020+Gerry-Forde@users.noreply.github.com> Date: Mon, 5 May 2025 20:16:56 +0100 Subject: [PATCH 3/7] Update artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc Co-authored-by: Lindsey Frazier --- .../rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc index e75cd18aee..13dec9fdc7 100644 --- a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc +++ b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc @@ -160,7 +160,7 @@ The Keycloak backend plugin supports link:https://opentelemetry.io/[OpenTelemetr === Labels -All counters include the `taskInstanceId` label, which uniquely identifies each scheduled fetch task. This allows you to trace failures back to individual task executions. For example: +All counters include the `taskInstanceId` label, which uniquely identifies each scheduled fetch task. You can use this label to trace failures back to individual task executions. For example: [source,subs="+attributes,+quotes"] ---- From be6c68ec702d106385eaab1c6c714855cdadee48 Mon Sep 17 00:00:00 2001 From: Gerry-Forde <63045020+Gerry-Forde@users.noreply.github.com> Date: Sat, 10 May 2025 11:33:02 +0100 Subject: [PATCH 4/7] RHIDP-5421 - Document which plugins in RHDH have metrics --- .../keycloak/keycloak-plugin-admin.adoc | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc index 13dec9fdc7..f4346a5631 100644 --- a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc +++ b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc @@ -160,13 +160,24 @@ The Keycloak backend plugin supports link:https://opentelemetry.io/[OpenTelemetr === Labels -All counters include the `taskInstanceId` label, which uniquely identifies each scheduled fetch task. You can use this label to trace failures back to individual task executions. For example: +All counters include the `taskInstanceId` label, which uniquely identifies each scheduled fetch task. You can use this label to trace failures back to individual task executions. + +Users can enter queries in the Prometheus UI or Grafana to explore and manipulate metric data. + +In the following example, the Prometheus Query Language (PromQL) expression returns the number of backend failures associated with a `taskInstanceId`: [source,subs="+attributes,+quotes"] ---- backend_keycloak_fetch_data_batch_failure_count_total{taskInstanceId="df040f82-2e80-44bd-83b0-06a984ca05ba"} 1 ---- +[NOTE] +==== +PromQL supports arithmetic operations, comparison operators, logical/set operations, aggregation, and various functions. Users can combine these features to analyze time-series data effectively. + +Additionally, the results can be visualized using Grafana. +==== + // === Use Case Example // Imagine your Keycloak instance is under-provisioned (e.g., low CPU/RAM limits), and the plugin is configured to send many parallel API requests. From c30b1133b642a6b7c546b489e56da0f635d7d322 Mon Sep 17 00:00:00 2001 From: Gerry-Forde <63045020+Gerry-Forde@users.noreply.github.com> Date: Sat, 10 May 2025 12:00:11 +0100 Subject: [PATCH 5/7] RHIDP-5421 - Document which plugins in RHDH have metrics --- .../keycloak/keycloak-plugin-admin.adoc | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc index f4346a5631..e1266ed8ec 100644 --- a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc +++ b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc @@ -150,7 +150,7 @@ The Keycloak backend plugin supports link:https://opentelemetry.io/[OpenTelemetr === Available Counters .Keycloak metrics -[cols="50%,50%", frame="all", options="header"] +[cols="60%,40%", frame="all", options="header"] |=== |Metric Name |Description @@ -164,13 +164,22 @@ All counters include the `taskInstanceId` label, which uniquely identifies each Users can enter queries in the Prometheus UI or Grafana to explore and manipulate metric data. -In the following example, the Prometheus Query Language (PromQL) expression returns the number of backend failures associated with a `taskInstanceId`: +.Examples +In the following examples, a Prometheus Query Language (PromQL) expression returns the number of backend failures. +.Example to get the number of backend failures associated with a `taskInstanceId` [source,subs="+attributes,+quotes"] ---- backend_keycloak_fetch_data_batch_failure_count_total{taskInstanceId="df040f82-2e80-44bd-83b0-06a984ca05ba"} 1 ---- +.Example to get the number of backend failures during the last hour + +[source,subs="+attributes,+quotes"] +---- +increase(backend_keycloak_fetch_data_batch_failure_count_total[1h]) +---- + [NOTE] ==== PromQL supports arithmetic operations, comparison operators, logical/set operations, aggregation, and various functions. Users can combine these features to analyze time-series data effectively. From 2f02d64b55ed28fee207b619c5795bc137e54861 Mon Sep 17 00:00:00 2001 From: Gerry-Forde <63045020+Gerry-Forde@users.noreply.github.com> Date: Sat, 10 May 2025 12:07:58 +0100 Subject: [PATCH 6/7] RHIDP-5421 - Document which plugins in RHDH have metrics --- .../rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc index e1266ed8ec..2ef672dc9e 100644 --- a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc +++ b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc @@ -164,7 +164,6 @@ All counters include the `taskInstanceId` label, which uniquely identifies each Users can enter queries in the Prometheus UI or Grafana to explore and manipulate metric data. -.Examples In the following examples, a Prometheus Query Language (PromQL) expression returns the number of backend failures. .Example to get the number of backend failures associated with a `taskInstanceId` From 9f0bbc2ca35ac5f00d30daddd875d4483023658b Mon Sep 17 00:00:00 2001 From: Gerry-Forde <63045020+Gerry-Forde@users.noreply.github.com> Date: Tue, 13 May 2025 14:26:19 +0100 Subject: [PATCH 7/7] Update artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc Co-authored-by: Oleksandr Andriienko --- .../rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc index 2ef672dc9e..ece6fdd6ac 100644 --- a/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc +++ b/artifacts/rhdh-plugins-reference/keycloak/keycloak-plugin-admin.adoc @@ -176,7 +176,7 @@ backend_keycloak_fetch_data_batch_failure_count_total{taskInstanceId="df040f82-2 [source,subs="+attributes,+quotes"] ---- -increase(backend_keycloak_fetch_data_batch_failure_count_total[1h]) +sum(backend_keycloak_fetch_data_batch_failure_count_total) - sum(backend_keycloak_fetch_data_batch_failure_count_total offset 1h) ---- [NOTE]