
:guide-id: event-metrics
:guide-title: Monitoring user activities with event metrics
:guide-summary: Event metrics provide an aggregated view of user activities in a {project_name} instance.
:guide-priority: 999
:guide-tile-visible: true
:version: 26.3.0

include::../attributes.adoc[]

[[event-metrics]]
= Monitoring user activities with event 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::[]


For now, only metrics for user events are captured.
For example, you can monitor the number of logins, login failures, or token refreshes performed.

The metrics are exposed using the standard metrics endpoint, and you can use it in your own metrics collection system to create dashboards and alerts.

The metrics are reported as counters per {project_name} instance.
The counters are reset on the restart of the instance.
If you have multiple instances running in a cluster, you will need to collect the metrics from all instances and aggregate them to get per a cluster view.

== Enable event metrics

To start collecting event metrics, enable metrics and enable the metrics for user events.

The following shows the required startup parameters:

[source,bash]
----
bin/kc.[sh|bat] start --metrics-enabled=true --event-metrics-user-enabled=true ...
----

By default, there is a separate metric for each realm.
To break down the metric by client and identity provider, you can add those metrics dimension using the configuration option `event-metrics-user-tags`.
This can be useful on installations with a small number of clients and IDPs.
This is not recommended for installations with a large number of clients or IDPs as it will increase the memory usage of {project_name} and as it will increase the load on your monitoring system.

The following shows how to configure {project_name} to break down the metrics by all three metrics dimensions:

[source,bash]
----
bin/kc.[sh|bat] start ... --event-metrics-user-tags=realm,idp,clientId ...
----

You can limit the events for which {project_name} will expose metrics.
See the {adminguide_link}#event-types[{adminguide_name} on event types] for an overview of the available events.

The following example limits the events collected to `LOGIN` and `LOGOUT` events:

[source,bash]
----
bin/kc.[sh|bat] start ... --event-metrics-user-events=login,logout ...
----

See link:{links_observability_metrics-for-troubleshooting-keycloak_url}[{links_observability_metrics-for-troubleshooting-keycloak_name}] for a description of the metrics collected.


== Relevant options

[cols="12a,4",role="options"]
|===
| |Value

|
[.options-key]#`+metrics-enabled+`# [.none]#icon:tools[role=options-build]#

[.options-description]#If the server should expose metrics.#

[role="options-extended"]
--
[.options-description-extended]#If enabled, metrics are available at the `/metrics` endpoint.#

*CLI:* `+--metrics-enabled+` +
*Env:* `+KC_METRICS_ENABLED+`
--



|
`+true+`, `+false+` (default)

|
[.options-key]#`+event-metrics-user-enabled+`# [.none]#icon:tools[role=options-build]#

[.options-description]#Create metrics based on user events.#

[role="options-extended"]
--


*CLI:* `+--event-metrics-user-enabled+` +
*Env:* `+KC_EVENT_METRICS_USER_ENABLED+`
--

Available only when metrics are enabled and feature user-event-metrics is enabled


|
`+true+`, `+false+` (default)

|
[.options-key]#`+event-metrics-user-events+`# 

[.options-description]#Comma-separated list of events to be collected for user event metrics.#

[role="options-extended"]
--
[.options-description-extended]#This option can be used to reduce the number of metrics created as by default all user events create a metric.#

*CLI:* `+--event-metrics-user-events+` +
*Env:* `+KC_EVENT_METRICS_USER_EVENTS+`
--

Available only when user event metrics are enabled

Use `remove_credential` instead of `remove_totp`, and `update_credential` instead of `update_totp` and `update_password`.
*Deprecated values: `+remove_totp+`, `+update_totp+`, `+update_password+`*

|
`+authreqid_to_token+`, `+client_delete+`, `+client_info+`, `+client_initiated_account_linking+`, `+client_login+`, `+client_register+`, `+client_update+`, `+code_to_token+`, `+custom_required_action+`, `+delete_account+`, `+execute_action_token+`, `+execute_actions+`, `+federated_identity_link+`, `+federated_identity_override_link+`, `+grant_consent+`, `+identity_provider_first_login+`, `+identity_provider_link_account+`, `+identity_provider_login+`, `+identity_provider_post_login+`, `+identity_provider_response+`, `+identity_provider_retrieve_token+`, `+impersonate+`, `+introspect_token+`, `+invalid_signature+`, `+invite_org+`, `+login+`, `+logout+`, `+oauth2_device_auth+`, `+oauth2_device_code_to_token+`, `+oauth2_device_verify_user_code+`, `+oauth2_extension_grant+`, `+permission_token+`, `+pushed_authorization_request+`, `+refresh_token+`, `+register+`, `+register_node+`, `+remove_credential+`, `+remove_federated_identity+`, `+remove_totp+` (deprecated), `+reset_password+`, `+restart_authentication+`, `+revoke_grant+`, `+send_identity_provider_link+`, `+send_reset_password+`, `+send_verify_email+`, `+token_exchange+`, `+unregister_node+`, `+update_consent+`, `+update_credential+`, `+update_email+`, `+update_password+` (deprecated), `+update_profile+`, `+update_totp+` (deprecated), `+user_disabled_by_permanent_lockout+`, `+user_disabled_by_temporary_lockout+`, `+user_info_request+`, `+verify_email+`, `+verify_profile+`

|
[.options-key]#`+event-metrics-user-tags+`# 

[.options-description]#Comma-separated list of tags to be collected for user event metrics.#

[role="options-extended"]
--
[.options-description-extended]#By default only `realm` is enabled to avoid a high metrics cardinality.#

*CLI:* `+--event-metrics-user-tags+` +
*Env:* `+KC_EVENT_METRICS_USER_TAGS+`
--

Available only when user event metrics are enabled


|
`+realm+`, `+idp+`, `+clientId+`


|===
