KeyCloak Metrics SPI

A Service Provider that adds a metrics endpoint to KeyCloak. The endpoint returns metrics data ready to be scraped by Prometheus.

Two distinct providers are defined:

MetricsEventListener to record the internal KeyCloak events
MetricsEndpoint to expose the data through a custom endpoint

The endpoint lives under <url>/auth/realms/<realm>/metrics. It will return data for all realms, no matter which realm you use in the URL (you can just default to /auth/realms/master/metrics).

Running the tests

$ ./gradlew test

Build

The project is packages as a jar file and bundles the prometheus client libraries.

$ ./gradlew jar

builds the jar and writes it to build/libs.

Usage

Just drop the jar into the providers subdirectory of your KeyCloak installation. To enable the event listener go to Manage -> Events -> Config. The Event Listeners configuration should have an entry named metrics-listener.

Metrics

For each metric, the endpoint returns 2 or more lines of information:

# HELP: A small description provided by the SPI.
# TYPE: The type of metric, namely counter and gauge. More info about types at prometheus.io/docs.
Provided there were any values, the last one recorded. If no value has been recorded yet, no more lines will be given.
In case the same metric have different labels, there is a different line for each one. By default all metrics are labeled by realm. More info about labels at prometheus.io/docs.

Example:

# HELP jvm_memory_bytes_committed Committed (bytes) of a given JVM memory area.
# TYPE jvm_memory_bytes_committed gauge
jvm_memory_bytes_committed{area="heap",} 2.00802304E8
jvm_memory_bytes_committed{area="nonheap",} 2.0217856E8

JVM performance

A variety of JVM metrics are provided

Generic events

Every single internal Keycloak event is being shared through the endpoint, with the descriptions Generic KeyCloak User event or Generic KeyCloak Admin event. Most of these events are not likely useful for the majority users but are provided for good measure. A complete list of the events can be found at Keycloak documentation.

Featured events

There are however a few events that are particularly more useful from a mobile app perspective. These events have been overriden by the SPI and are described more thoroughly below.

keycloak_logins

This counter counts every login performed by a non-admin user. It also distinguishes logins by the utilised identity provider by means of the label provider.

# HELP keycloak_logins Total successful logins
# TYPE keycloak_logins gauge
keycloak_logins{realm="test",provider="keycloak",} 3.0
keycloak_logins{realm="test",provider="github",} 2.0

keycloak_failed_login_attempts

This counter counts every login performed by a non-admin user that fails, being the error described by the label error. It also distinguishes logins by the identity provider used by means of the label provider.

# HELP keycloak_failed_login_attempts Total failed login attempts
# TYPE keycloak_failed_login_attempts gauge
keycloak_failed_login_attempts{realm="test",provider="keycloak",error="invalid_user_credentials"} 6.0
keycloak_failed_login_attempts{realm="test",provider="keycloak",error="user_not_found"} 2.0

keycloak_registrations

This counter counts every new user registration. It also distinguishes registrations by the identity provider used by means of the label provider.

# HELP keycloak_registrations Total registered users
# TYPE keycloak_registrations gauge
keycloak_registrations{realm="test",provider="keycloak",} 1.0
keycloak_registrations{realm="test",provider="github",} 1.0

aabouzaid / keycloak-metrics-spi