
:guide-id: metrics-for-troubleshooting-keycloak
:guide-title: Self-provided metrics
:guide-summary: Learn about key metrics that {project_name} provides
:guide-priority: 999
:guide-tile-visible: false
:version: 26.2.2

include::../attributes.adoc[]

[[metrics-for-troubleshooting-keycloak]]
= Self-provided metrics

ifeval::["" == "true"]
WARNING: This {section} is describing a feature which is currently in preview.
ifeval::["" == ""]
Please provide your feedback while we’re continuing to work on this.
endif::[]
ifeval::["" != ""]
Please provide your feedback by link:[joining this discussion] while we’re continuing to work on this.
endif::[]
endif::[]



This is part of the link:{links_observability_metrics-for-troubleshooting_url}[{links_observability_metrics-for-troubleshooting_name}] {section}.

== Prerequisites

* Metrics need to be enabled for {project_name}. Follow the link:{links_observability_configuration-metrics_url}[{links_observability_configuration-metrics_name}] {section} for more details.
* A monitoring system collecting the metrics.

== Metrics

=== User Event Metrics

User event metrics are disabled by default. See link:{links_observability_event-metrics_url}[{links_observability_event-metrics_name}] 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 link:{links_observability_metrics-for-troubleshooting_url}[{links_observability_metrics-for-troubleshooting_name}] or proceed to link:{links_observability_metrics-for-troubleshooting-jvm_url}[{links_observability_metrics-for-troubleshooting-jvm_name}].


