Keycloak Database Metrics

This documentation covers the information about Keycloak’s connection to the database Keycloak.

Enable Keycloak metrics

Keycloak exposes metrics on the management interface endpoint /metrics. To enable, use the build time option --metrics-enabled=true.

On a Kubernetes cluster, using the Keycloak Operator, metrics can be enabled by in the Keycloak CR addionalOptions as shown below:

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  labels:
    app: keycloak
  name: keycloak
spec:
  additionalOptions:
    - name: metrics-enabled
      value: 'true'

Additional information can be found here.

Database connection pool

Configure Keycloak to use a fixed size database connection pool. See Concepts for database connection pools for more information.

If there is a high count of threads waiting for a database connection, increasing the database connection pool size is not always the best option. It might overload the database which would then become the bottleneck. Consider the following options instead:

  • Reduce the number of HTTP worker threads using the option http-pool-max-threads to make it match the available database connections, and thereby reduce contention and resource usage in Keycloak and increase throughput.

  • Check which database statements are executed on the database. If you see, for example, a lot of information about clients and groups being fetched, and the users and realms cache are full, this might indicate that it is time to increase the sizes of those caches and see if this reduces your database load.
Metric Description

agroal_available_count

Idle database connections.

agroal_active_count

Database connections used in ongoing transactions.

agroal_awaiting_count

Threads waiting for a database connection to become available.

Additional information on the Keycloak metrics endpoint can be found here.