diff --git a/docs/documentation/release_notes/topics/26_1_0.adoc b/docs/documentation/release_notes/topics/26_1_0.adoc index a6e0e597cb9..cd8172c95f1 100644 --- a/docs/documentation/release_notes/topics/26_1_0.adoc +++ b/docs/documentation/release_notes/topics/26_1_0.adoc @@ -134,26 +134,12 @@ darkMode=false Alternatively, you can disable dark mode support for the built-in Keycloak themes on a per-realm basis by turning off the *Dark mode* setting under the *Theme* tab in the realm settings. -= Password validations counter metric += Metrics on password hashing -There is a new counter metric available counting how many password validations were performed by Keycloak. -Available tags are: +There is a new metric available counting how many password validations were performed by {project_name}. +This allows you to better assess where CPU resources are used, and can feed into your sizing calculations. -* `realm` -* `algorithm` - algorithm used for hashing password -* `hashing_strength` - string denoting strength of hashing algorithm, for example, number of iterations -* `outcome` - outcome of password validation -** `valid` - password was correct -** `invalid` - password was incorrect -** `error` - error when creating hash of the password - -To configure what tags are available provide a comma-separated list of tag names to the following option `spi-credential-keycloak-password-validations-counter-tags`. -By default, all tags are enabled. - -Example of the metric: ----- -keycloak_credentials_password_hashing_validations_total{algorithm="argon2",hashing_strength="Argon2id-1.3[m=7168,t=5,p=1]",outcome="valid",realm="master",} 3.0 ----- +See https://www.keycloak.org/observability/metrics-for-troubleshooting-http[Keycloak metrics] and https://www.keycloak.org/high-availability/concepts-memory-and-cpu-sizing#_measuring_the_activity_of_a_running_keycloak_instance[Concepts for sizing CPU and memory resources] for more details. = Sign out all active sessions in admin console now effectively removes all sessions diff --git a/docs/documentation/tests/src/test/resources/ignored-links b/docs/documentation/tests/src/test/resources/ignored-links index 9fc8577a407..48f76390110 100644 --- a/docs/documentation/tests/src/test/resources/ignored-links +++ b/docs/documentation/tests/src/test/resources/ignored-links @@ -38,4 +38,8 @@ https://kubernetes.io/docs/tutorials/stateful-application/basic-stateful-set/#ro https://stackapps.com/apps/oauth/register # Failing because of broken certificate, can likely be restored later. https://docs.kantarainitiative.org* -https://saml.xml.org* \ No newline at end of file +https://saml.xml.org* +# To be removed once KC 26.1 has been released +https://www.keycloak.org/server/logging#_configuring_levels_as_individual_options +https://www.keycloak.org/observability/* +https://www.keycloak.org/high-availability/concepts-memory-and-cpu-sizing#_measuring_the_activity_of_a_running_keycloak_instance \ No newline at end of file diff --git a/docs/guides/observability/configuration-metrics.adoc b/docs/guides/observability/configuration-metrics.adoc index 89b9b801bb3..c37dbdd2737 100644 --- a/docs/guides/observability/configuration-metrics.adoc +++ b/docs/guides/observability/configuration-metrics.adoc @@ -53,32 +53,8 @@ system_load_average_1m 4.005859375 ... ---- -== Available Metrics +== Next steps -The table below summarizes the available metrics groups: - -[%autowidth] -|=== -|Metric | Description - -|System -|A set of system-level metrics related to CPU and memory usage. - -|JVM -|A set of metrics from the Java Virtual Machine (JVM) related to GC, and heap. - -|Database -|A set of metrics from the database connection pool, if using a database. - -|HTTP -|A set of global and individual metrics from the HTTP endpoints - -|Cache -|A set of metrics from Infinispan caches. See <@links.server id="caching"/> for more details. - -|Keycloak -|A set of metrics from Keycloak events. See <@links.observability id="event-metrics"/> for more details. - -|=== +Read the {sections} <@links.observability id="keycloak-service-level-indicators"/> and <@links.observability id="metrics-for-troubleshooting"/> to see how to use the metrics. diff --git a/docs/guides/observability/event-metrics.adoc b/docs/guides/observability/event-metrics.adoc index 67359bb39af..f6497a23251 100644 --- a/docs/guides/observability/event-metrics.adoc +++ b/docs/guides/observability/event-metrics.adoc @@ -43,19 +43,6 @@ The following example limits the events collected to `LOGIN` and `LOGOUT` events <@kc.start parameters="... --event-metrics-user-events=login,logout ..."/> -All error events will be collected with the primary event type and will have the `error` tag filled with the error code. - -The snippet below is an example of a response provided by the metric endpoint: - -[source] ----- -# HELP keycloak_user_events_total Keycloak user events -# TYPE keycloak_user_events_total counter -keycloak_user_events_total{client_id="security-admin-console",error="",event="code_to_token",idp="",realm="master",} 1.0 -keycloak_user_events_total{client_id="security-admin-console",error="",event="login",idp="",realm="master",} 1.0 -keycloak_user_events_total{client_id="security-admin-console",error="",event="logout",idp="",realm="master",} 1.0 -keycloak_user_events_total{client_id="security-admin-console",error="invalid_user_credentials",event="login",idp="",realm="master",} 1.0 ----- - +See <@links.observability id="metrics-for-troubleshooting-keycloak"/> for a description of the metrics collected. diff --git a/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc b/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc new file mode 100644 index 00000000000..f34439960d2 --- /dev/null +++ b/docs/guides/observability/metrics-for-troubleshooting-keycloak.adoc @@ -0,0 +1,92 @@ +<#import "/templates/guide.adoc" as tmpl> +<#import "/templates/links.adoc" as links> + +<@tmpl.guide +title="{project_name} self-provided metrics" +summary="Learn about key metrics that {project_name} provides" +tileVisible="false" +> + +<#include "partials/prerequisites-metrics-troubleshooting.adoc" /> + +== Metrics + +=== User Event Metrics + +User event metrics are disabled by default. See <@links.observability id="event-metrics"/> on how to enable them and how to configure which tags are recorded. + +|=== +|Metric |Description + +m| keycloak_user_events_total +| Counting the occurrence of user events. + +|=== + +==== +*Tags* + +The tags `client_id` and `idp` are disabled by default to avoid a too high cardinality. + +`realm`:: Realm +`client_id`:: Client ID +`idp`:: Identity Provider +`event`:: User event, for example `login` or `logout`. See the {adminguide_link}#event-types[{adminguide_name} on event types] for an overview of the available events. +`error`:: Error specific to the event, for example `invalid_user_credentials` for the event `login`. Empty string if no error occurred. +==== + +The snippet below is an example of a response provided by the metric endpoint: + +[source] +---- +# HELP keycloak_user_events_total Keycloak user events +# TYPE keycloak_user_events_total counter +keycloak_user_events_total{client_id="security-admin-console",error="",event="code_to_token",idp="",realm="master",} 1.0 +keycloak_user_events_total{client_id="security-admin-console",error="",event="login",idp="",realm="master",} 1.0 +keycloak_user_events_total{client_id="security-admin-console",error="",event="logout",idp="",realm="master",} 1.0 +keycloak_user_events_total{client_id="security-admin-console",error="invalid_user_credentials",event="login",idp="",realm="master",} 1.0 +---- + +=== Password hashing + +|=== +|Metric |Description + +m| keycloak_credentials_password_hashing_validations_total +| Counting password hashes validations. + +|=== + +==== +*Tags* + +`realm`:: Realm +`algorithm`:: Algorithm used for hashing password, for example `argon2` +`hashing_strength`:: String denoting strength of hashing algorithm, for example, number of iterations depending on the algorithm. For example, `Argon2id-1.3[m=7168,t=5,p=1]` +`outcome`:: Outcome of password validation. +Possible values: ++ +-- +`valid`:: Password correct +`invalid`:: Password incorrect +`error`:: Error when creating the hash of the password +-- +==== + +To configure what tags are available provide a comma-separated list of tag names to the following option `spi-credential-keycloak-password-validations-counter-tags`. +By default, all tags are enabled. + +The snippet below is an example of a response provided by the metric endpoint: + +[source] +---- +# HELP keycloak_credentials_password_hashing_validations_total Password validations +# TYPE keycloak_credentials_password_hashing_validations_total counter +keycloak_credentials_password_hashing_validations_total{algorithm="argon2",hashing_strength="Argon2id-1.3[m=7168,t=5,p=1]",outcome="valid",realm="realm-0",} 39949.0 +---- + +== Next steps + +Return back to the <@links.observability id="metrics-for-troubleshooting"/> or proceed to <@links.observability id="metrics-for-troubleshooting-jvm"/>. + + diff --git a/docs/guides/observability/metrics-for-troubleshooting.adoc b/docs/guides/observability/metrics-for-troubleshooting.adoc index 40d450e6cff..baa8ea0c496 100644 --- a/docs/guides/observability/metrics-for-troubleshooting.adoc +++ b/docs/guides/observability/metrics-for-troubleshooting.adoc @@ -41,6 +41,7 @@ You should always confirm the configuration change by conducting a performance t == List of {project_name} key metrics +* <@links.observability id="metrics-for-troubleshooting-keycloak"/> * <@links.observability id="metrics-for-troubleshooting-jvm"/> * <@links.observability id="metrics-for-troubleshooting-database"/> * <@links.observability id="metrics-for-troubleshooting-http"/>