Enabling Keycloak Event Metrics

Learn how to enable and use Keycloak Event Metrics
This guide is describing a feature which is currently in preview. Please provide your feedback while we’re continuing to work on this.

Event metrics can provide admins an overview of the different activities in a Keycloak instance. 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 Keycloak 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 metrics, enable the feature user-event-metrics, enable metrics, and enable the metrics for user events.

The following shows the required startup parameters:

bin/kc.[sh|bat] start --features=user-event-metrics --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 Keycloak and as it will increase the load on your monitoring system.

The following shows how to configure Keycloak to break down the metrics by all three metrics dimensions:

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

You can limit the events for which Keycloak will expose metrics. See the Server Administration Guide on event types for an overview of the available events.

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

bin/kc.[sh|bat] start ... --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:

# 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

Relevant options

Value

metrics-enabled

If the server should expose metrics.

If enabled, metrics are available at the /metrics endpoint.

CLI: --metrics-enabled
Env: KC_METRICS_ENABLED

true, false (default)

event-metrics-user-enabled

Preview: Create metrics based on user events.

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)

event-metrics-user-events

Preview: Comma-separated list of events to be collected for user event metrics.

Reduce the number of metrics. If empty or not set, all 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

event-metrics-user-tags

Preview: Comma-separated list of tags to be collected for user event metrics.

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
On this page
Edit this guide