Monitoring Keycloak

Edit online

You can monitor your Keycloak environment with the Instana Keycloak sensor. After you install the Instana host agent, the agent automatically deploys the Keycloak sensor, which collects real-time metrics. You can view the metrics in the Instana UI.

The Keycloak sensor provides comprehensive monitoring capabilities for your Keycloak environment, including performance metrics, user events, and health monitoring.

Support information

Edit online

To make sure that the Keycloak sensor is compatible with your current setup, check the following support information sections:

Supported versions and support policy

Edit online

The following table shows the latest supported version and support policy:

Table 1. Latest supported version and support policy
Technology	Support policy	Latest technology version	Latest supported version
Keycloak (Quarkus-based)	On demand	26.5	26.5

For more information about the support policy, see Support strategy for sensors.

Configuring Keycloak monitoring

Edit online

After you install the agent, the Keycloak sensor is enabled by default. To start Keycloak monitoring, enable the required settings in Keycloak.

Enabling metrics and health monitoring in Keycloak

Edit online

To collect performance metrics, user events, and health metrics from Keycloak, ensure that the following command-line flags or K8s environment variables are configured.

Table 2. Command Line and Environment Variables to enable Keycloak Metrics Collection
CLI flags or environment variables	Value
--metrics-enabled/ KC_METRICS_ENABLED	`true`
--event-metrics-user-tags / KC_EVENT_METRICS_USER_TAGS	`realm` or `clientId`
--health-enabled/ KC_HEALTH_ENABLED	`true`
--event-metrics-user-events / KC_EVENT_METRICS_USER_EVENTS	`login`, `logout`, `client_login`, `refresh_token`, `register`, or `code_to_token`

For more information, see the Keycloak User Events documentation.

Optional: Configuring the polling rate

Edit online

You can configure how often Instana polls Keycloak to collect data and metrics by using the poll_rate parameter in the agent configuration.yaml file (*instanaAgentDir*/etc/instana/configuration.yaml) as shown in the following example:

com.instana.plugin.keycloak:
  enabled: true # Default value is true
  poll_rate: 1 # values are in seconds. Default value is 1 second.

Note: If no specific polling interval is provided, the default polling interval is 1 second.

Viewing metrics

Edit online

To view the metrics, select Infrastructure from the navigation menu in the Instana UI, click a specific monitored host, and then you can see a host dashboard with all the collected metrics and monitored processes.

Note: Metrics can also be collected through a Prometheus sensor. You can create custom dashboards by using the collected metrics.

The Keycloak sensor collects the following performance metrics:

Performance metrics

Edit online

The following metrics are collected from the Keycloak instance:

Table 3. Performance metrics collected
Performance metric	Description	Metric name	Unit
User Event Metrics	Tracks occurrence of user events with tags: `realm`, `client_id`, `event`, or `error`	`keycloak.user`	Count
HTTP Server Request Metrics	Measures the requests processed duration for URIs matching `/realms/{realm}/protocol/{protocol}`, with tags (`uri`, `method`, `status`, or `outcome`)	`http.server.requests`	Milliseconds

User Event metrics

Keycloak user events are collected and categorized by using tags, and the resulting data is rendered as graphs in the Instana UI.

Table 4. User Event Metrics
Data point	Filter by tag	Group by tag	Description
Successful logins	event=`login` and error=`""`		Number of successful login attempts
Login attempts	event=`login`		Total number of login attempts
Failed login attempts	event=`login` and error!=`""`		Number of failed login attempts
Successful client logins	event=`login` and error=`""`	`client_id`	Number of successful login attempts per client id
Failed client logins	event=`login` and error!=`""`	`client_id`	Number of failed login attempts per client id
Successful realm logins	event=`login` and error=`""`	`realm`	Number of successful login attempts per realm
Failed realm logins	event=`login` and error!=`""`	`realm`	Number of failed login attempts per realm
Login errors	event=`login` and error!=`""`	`error`	Failed login events by error type
Registration errors	event=`register` and error!=`""`	`error`	User registration by error types
Refresh tokens	event=`refresh_token` and error=`""`	`client_id`	Number of refresh token requests per client id
Refresh token errors	event=`refresh_token` and error!=`""`	`client_id`	Number of refresh token errors per client id
Registration requests	event=`register` and error=`""`	`realm`	Number of registration requests per realm
Registration errors	event=`register` and error!=`""`	`realm`	Number of registration errors per realm
Code to token requests	event=`code_to_token` and error=`""`	`client_id`	Number of authorization code to token exchanges requests per client id
Code to token errors	event=`code_to_token` and error!=`""`	`client_id`	Number of failed code to token exchanges per client id
Top 5 Clients	-	`client_id`	Top 5 client IDs
Top 5 Realms	-	`realm`	Top 5 realms

HTTP Server Request metrics

The HTTP Server Request metrics are derived in the UI as follows:

Table 5. HTTP Server Request metrics
Data point	Filter by tag	Group by tag	Description
Request error distribution(4xx or 5xx)	status=`4xx` or `5xx`	`status`	Distribution of request errors
Request duration by uri	-	`uri`	Top 5 request duration by uri in milliseconds

Health metrics

Keycloak exposes health metrics through its /health endpoint, which indicate the runtime readiness and availability of the server. Following metrics are typically collected:

Table 6. Health metrics
Health check	Description
Overall Health	Overall health of the Keycloak instance
Database Connectivity	Indicates if Keycloak can connect to its database
Cluster Health	Status of Keycloak cluster nodes and inter-node communication